Security Monitor API Resources

API Summary

Operation Method Endpoint
Report Packs
List Report Packs GET /security-monitor/v1/report-packs
Get a Report Pack GET /security-monitor/v1/report-packs/{reportPackId}
List Data Stores GET /security-monitor/v1/report-packs/{reportPackId}/data-stores
Get a Data Store GET /security-monitor/v1/report-packs/{reportPackId}/data-stores/{dataStoreId}
List Data Sources GET /security-monitor/v1/report-packs/{reportPackId}/data-sources
Report Data
Get a Report GET /security-monitor/v1/report-packs/{reportPackId}/data{?startDate,endDate,aggregation,dimensions,metrics,limit,offset,filterParams,sortParams}

List Report Packs

Returns name, id, and timezone for all report packs created for your account. Report packs are a collection of reports fed by data sources and other components. If you already have reports pack details on hand, see List Data Stores.

GET /security-monitor/v1/report-packs

Status 200 application/json

Response:

[
    {
        "id": 12332,
        "name": "Sample 1",
        "isActive": true,
        "type": "qos",
        "subType": "QoS_Security_Monitor",
        "timezone": "GMT"
    },
    {
        "id": 121234,
        "name": "Sample 1",
        "isActive": true,
        "type": "ma",
        "subType": "QoS_Security_Monitor",
        "timezone": "EST5EDT"
    }

Relevant data members:

Member Type Description
id Number Integer ID of the report pack.
name String Name of the report pack.
subType String This field is meant for internal use and will be removed.
timezone String Timezone in which the data is returned.
type String This field is meant for internal use and will be removed.

Get a Report Pack

Details include name of the report pack, data sources, and metrics and dimensions used in the report pack.

GET /security-monitor/v1/report-packs/{reportPackId}

Example: /security-monitor/v1/report-packs/121234

Parameter Type Sample Description
Required
reportPackId Number 121234 Report pack ID

Status 200 application/json

Response:

{
    "id": 12332,
    "name": "Sample 1",
    "isActive": true,
    "type": "qos",
    "subType": "QoS_Security_Monitor",
    "dataSources": [
        {
            "id": 2673,
            "name": "Security Monitor Data Source"
        }
    ],
    "dimensions": [
        {
            "id": 43,
            "name": "Time",
            "type": "standard"
        },
        {
            "id": 958,
            "name": "City",
            "type": "standard"
        },
        {
            "id": 956,
            "name": "Client IP",
            "type": "standard"
        },
        {
            "id": 957,
            "name": "Country",
            "type": "standard"
        }
    ],
    "metrics": [
        {
            "id": 546,
            "name": "Contributing Rules"
        },
        {
            "id": 552,
            "name": "Requests Warned",
            "description": "Number of request warned"
        },
        {
            "id": 544,
            "name": "Requests Denied"
        },
        {
            "id": 3,
            "name": "Rules Triggered"
        }
    ],
    "filters": null,
    "dataStores": [
        {
            "id": 939,
            "name": "sample data store 1",
            "type": "standard",
            "description": "Sample Description"
        },
        {
            "id": 952,
            "name": "sample data store 2",
            "type": "custom",
            "description": "Sample Description"
        }
    ],
    "timezone": "GMT"
}

Relevant data members:

Member Type Description
dataSources Array All data sources for the report pack. A data source is a collection of raw log data with detailed information on each access to your digital property made by a user. Each data source object provides information on name of the data source and its ID.
dataStores Array All data stores for the report pack. A data store is a collection of dimensions and metrics stored in a data base. Each data store object provides information on the name, type, short description, and ID of the data store.
dimensions Array All dimensions for the report pack. The dimension is a field that acts like a key in data exploration. It answers questions such as who, what, where, and which. Each dimension object provides information on the name, type, and ID of the dimension.
filters null This field is meant for internal use and will be removed.
id Number Integer ID of the report pack.
metrics Array All metrics for the report pack. A metric is a numeric aggregation against one or more dimensions. Each metric object provides information on the name and ID of the metric. It answers questions on volume of activity or attack.
name String Name of the report pack.
subType String This field is meant for internal use and will be removed.
timezone String Timezone in which the data is returned.
type String This field is meant for internal use and will be removed.

List Data Stores

A data store is a collection of dimensions and metrics stored in a database that you can use to create a sub-set and configure reports suited to your requirements. Data store details help you determine the combination of dimensions and metrics to query. Each report pack comes with its standard data stores. You cannot combine dimensions and metrics across data stores.

GET /security-monitor/v1/report-packs/{reportPackId}/data-stores

Example: /security-monitor/v1/report-packs/121234/data-stores

Parameter Type Sample Description
Required
reportPackId Number 121234 Report pack ID.

Status 200 application/json

Response:

[
    {
        "id": 939,
        "name": "sample data store",
        "type": "standard",
        "dimensions": [
            {
                "id": 958,
                "name": "City",
                "description": "City from which viewer requested media",
                "type": "standard"
            },
            {
                "id": 956,
                "name": "Client IP",
                "description": "SD Dimension",
                "type": "standard"
            }
        ],
        "metrics": [
            {
                "id": 546,
                "name": "Contributing Rules",
                "description": "Contributing Rules"
            },
            {
                "id": 552,
                "name": "Requests Warned",
                "description": "Number of request warned"
            },
            {
                "id": 3,
                "name": "Rules Triggered",
                "description": "Number of rules triggered"
            }
        ],
        "aggregationInSeconds": 60,
        "purgeIntervalInDays": 8,
        "maxQueryDurationInMinutes": 1440,
        "description": "sample data store description"
    },
    {
        "id": 952,
        "name": "Time only cubes for security_monitor",
        "type": "standard",
        "description": "Time only cubes for security_monitor",
        "dimensions": [
            {
                "id": 43,
                "name": "Time",
                "description": "Time as per time zone specified in the report",
                "type": "standard"
            }
        ],
        "metrics": [
            {
                "id": 552,
                "name": "Requests Warned",
                "description": "Number of request warned"
            },
            {
                "id": 3,
                "name": "Rules Triggered",
                "description": "Number of rules triggered"
            }
        ],
        "aggregationInSeconds": 60,
        "purgeIntervalInDays": 8,
        "maxQueryDurationInMinutes": 1440
    }
]

Relevant data members:

Member Type Description
aggregation Number Time (seconds) over which data is aggregated.
description String Text describing the data store.
dimensions Array All dimensions for the data store. Dimension is a field that acts like a key in data exploration. It answers questions such as who, what, where, and which. Each dimension object provides information on the ID, name, type, and description of the dimension.
id Number ID of the data store.
maxQueryDurationInMinutes Number Maximum duration (in minutes) for which a user can query a data store.
metrics Array All metrics for the data store. A metric is a numeric aggregation against one or more dimensions. It answers questions on volume of activity or attack. Each metric object provides information on the name, description, and ID of the metric.
name String Name of the data store.
purgeIntervalInDays Number Number of days for which the data store keeps data.
type String Type of data store. Security Monitor uses standard data stores.

Get a Data Store

Details include list of dimensions, list of metrics, aggregation interval, purge interval, and maximum allowed query interval, and so on.

GET /security-monitor/v1/report-packs/{reportPackId}/data-stores/{dataStoreId}

Example: /security-monitor/v1/report-packs/121234/data-stores/939

Parameter Type Sample Description
Required
dataStoreId Number 939 Data store ID.
reportPackId Number 121234 Report pack ID.

Status 200 application/json

Response:

{
    "aggregationInSeconds": 60,
    "description": "sample data store description",
    "id": 939,
    "maxQueryDurationInMinutes": 1440,
    "name": "sample data store",
    "purgeIntervalInDays": 8,
    "type": "standard",
    "dimensions": [
        {
            "description": "City from which viewer requested media",
            "id": 958,
            "name": "City",
            "type": "standard"
        },
        {
            "description": "SD Dimension",
            "id": 956,
            "name": "Client IP",
            "type": "standard"
        }
    ],
    "metrics": [
        {
            "description": "Contributing Rules",
            "id": 546,
            "name": "Contributing Rules"
        },
        {
            "description": "Number of request warned",
            "id": 552,
            "name": "Requests Warned"
        },
        {
            "description": "Number of rules triggered",
            "id": 3,
            "name": "Rules Triggered"
        }
    ]
}

Relevant data members:

Member Type Description
aggregation Number Time (seconds) over which data is aggregated.
description String Text describing the data store.
dimensions Array All dimensions for the data store. Dimension is a field that acts like a key in data exploration. Each dimension object provides information on ID, name, type, and description of the dimension. It answers questions such as who, what, where, and which.
id Number data store ID.
maxQueryDurationInMinutes Number Maximum duration (in minutes) for which a user can query a data store.
metrics Array All metrics for the data store. A metric is a numeric aggregation against one or more dimensions. Each metric object provides information on the name, description, and ID of the metric. It answers questions on volume of activity or attack.
name String Name of the data store.
purgeIntervalInDays Number Number of days for which the data store keeps data.
type String Type of data store. Security Monitor uses standard data stores.

List Data Sources

A data source is a set of IDs (Policy IDs) that were assigned by you and Akamai in Luna Control Center for a firewall policy during WAF configuration.

GET /security-monitor/v1/report-packs/{reportPackId}/data-sources

Example: /security-monitor/v1/report-packs/121234/data-sources

Parameter Type Sample Description
Required
reportPackId Number 121234 Report pack ID.

Status 200 application/json

Response:

[
    {
        "id": 2673,
        "name": "Security Monitor Data Source",
        "type": "clientside_qos1_sm",
        "dsType": "policyId",
        "values": [
            "111_375", "mob_1183", "16767", "444_374",
            "432_336", "DFN_667", "DRFB_2968", "188279"
        ]
    }
]

Relevant data members:

Member Type Description
configPath String This field is meant for internal use and will be removed.
dsType String Data Source type. For Security Monitor, the policy ID.
id Number Data Source ID.
name String Name of the Data Source.
values Array List of Policy IDs.

Get a Report

This operation gets data for a specific report based on filter query parameters. Use filterParams and sortParams to filter and sort data. The values for these parameters must be UTF–8 encoded JSON strings as detailed below.

GET /security-monitor/v1/report-packs/{reportPackId}/data{?startDate,endDate,aggregation,dimensions,metrics,limit,offset,filterParams,sortParams}

Example: /security-monitor/v1/report-packs/121234/data?startDate=03%2F22%2F2014%3A15%3A30&endDate=03%2F23%2F2014%3A15%3A30&aggregation=month&dimensions=958%2C956&metrics=546%2C552%2C3&limit=300&offset=0&filterParams=%5B%7B%22type%22%3A%22dimension%22%2C%22values%22%3A%5B%22GB%22%5D%2C%22id%22%3A4%2C%22condition%22%3A%22in%22%7D%2C%7B%22type%22%3A%22metric%22%2C%22values%22%3A%5B16%5D%2C%22id%22%3A155%2C%22condition%22%3A%22gt%22%7D%5D&sortParams=%5B%7B%22type%22%3A%22metric%22%2C%22order%22%3A%22asc%22%2C%22id%22%3A40%7D%5D

Headers:

  • Accept: application/json

Parameter Type Sample Description
Optional
aggregation String month Aggregation in which the data must be grouped. It can be a number representing the aggregation in seconds or one of the following possible values day, week, month, year. If passed as a number, the allowed value is one of the aggregations of the available data stores available from List Data Stores.
dimensions String 958,956 Comma-separated dimension IDs. Use List Data Stores to get these values.
endDate String 03/23/2014:15:30 End date string in format MM/dd/yyyy:HH:mm. The time part is optional and should be in the 24-hour format.
filterParams String [{"type":"dimension","values":["GB"],"id":4,"condition":"in"},{"type":"metric","values":[16],"id":155,"condition":"gt"}] The UTF–8 URL-encoded JSON string of the filter parameters based on which the data is filtered. The structure of the JSON is expained above. By default, the data is not filtered.
limit Number 300 Number of rows to return. Value must lie between 1 and 10000 inclusive. If not specified, 300 rows are returned, by default.
metrics String 546,552,3 Comma-separated metric IDs. Use List Data Stores to get these values.
offset Number 0 The offset of the row from which the data starts. This parameter must be used along with limit to get batches of data. For instance, if there are 1000 records in the result, 10 calls can be made with progressing offset. That is, first call with limit=100 and offset=0, second call with limit=100 and offset=100, and so forth. The default value is 0
reportPackId Number 121234 Report pack ID.
sortParams String [{"type":"metric","order":"asc","id":40}] The UTF–8 URL-encoded JSON string of the sort parameters based on which the data is sorted. The structure of the JSON is explained above. By default, the data is sorted by time, if time is selected as one of the dimensions. If time is not one of the dimensions, data is sorted by the first metric in descending order.
startDate String 03/22/2014:15:30 Start date string in the format MM/dd/yyyy:HH:mm. The time part is optional and should be in the 24-hour format.

All filterParams members are required:

Member Type Description
condition Enumeration Condition specifier. Prepending n negates the condition. For Dimensions: in, nin, contains, ncontains, starts, nstarts, ends, nends. For Metrics: eq, neq, gt, gte, lt, lte.
id Number ID of the filtering entity (dimension/metric).
type Enumeration The parameter ID provided, either dimension or metric.
values Array List of values used to filter the result.

All sortParams members are required:

Member Type Description
id Number ID of the sorting entity.
order Enumeration Either asc (ascending) or desc (descending) sort order.
type Enumeration Determines if the sorting is based on dimension or metric.

Status 200 application/json

Response:

{
    "columns": [
        {
            "type": "dimension",
            "name": "Time",
            "description": "Time as per time zone specified in the report   ",
            "index": 0
        },
        {
            "type": "dimension",
            "name": "Country",
            "description": "Country from which viewer requested media",
            "index": 1
        },
        {
            "type": "metric",
            "name": "Denied",
            "description": "Number of request denied",
            "index": 2,
            "aggregate": "418",
            "peak": "156",
            "unit": null
        }
    ],
    "rows": [
        [ "1415837040", "US", "156" ],
        [ "1415836980", "US", "113" ],
        [ "1415836920", "US", "95" ],
        [ "1415836860", "US", "54" ]
    ],
    "metaData": {
        "aggregation": 60,
        "limit": 50,
        "startTimeInEpoch": 1415836800,
        "hasMoreData": false,
        "timeZone": "GMT",
        "offset": 0,
        "reportPack": "Security Monitor Report Pack",
        "endTimeInEpoch": 1415837100
    }
}

Relevant data members:

Member Type Description
aggregation Number Time (seconds) over which data is aggregated.
columns Array Each column provides details such as the type (metric/dimension), name, description, index of the column. If the column is of type metric, then aggregate value of the metric and the max value (peak) is also returned.
endTimeInEpoch Number End time of the query in Unix epoch seconds.
hasMoreData Boolean Enabled if there are more data rows (than the rows returned by the query) that satisfy the query.
limit Number Number of data rows returned.
offset Number The offset of the row from which the data starts.
reportPack String Name of the report pack.
rows Array Data rows.
startTimeInEpoch Number Start time of the query in Unix epoch seconds.
timezone String Timezone of the report pack or timezone in which the data is returned.

Here is an example of a request. Assume that the dimension IDs 12,34 represent time and country respectively and the metric ID 56 represents the metric Number of requests denied. Assume you also need the following data:

  • Data for the United States only for Nov 13, 2014 between 12 AM and 12:05 AM.
  • Data only for requests denied numbering 51 or more.
  • Data for requests denied sorted in descending order.

The request URL should look like this:

https://{host}/security-monitor/v1/report-packs/123456/data?dimensions=12,34&metrics=56&startDate=11/13/2014:00:00&endDate=11/13/2014:00:05&limit=50
&filterParams=%5B%7B%22id%22%3A78%2C%22type%22%3A%22dimension%22%2C%22values%22%3A%5B%22US%22%5D%2C%22condition%22%3A%22in%22%7D%2C%7B%22id%22%3A651%2C%22type%22%3A%22metric%22%2C%22values%22%3A%5B50%5D%2C%22condition%22%3A%22gt%22%7D%5D
&sortParams=%5B%7B%22id%22%3A651%2C%22type%22%3A%22metric%22%2C%22order%22%3A%22desc%22%7D%5D

In this example, the value of filterParams is a UTF–8 encoded representation of this JSON string:

[{"id":12,"type":"dimension","values":["US"],"condition":"in"},{"id":56,"type":"metric","values":[50],"condition":"gt"}]

The sortParams value is a UTF–8 encoded representation of this JSON string:

[{"id":651,"type":"metric","order":"desc"}]

Last modified: 12/12/2016