# Vertical Feeds Statistics API (tca-0307–0311, tca-0317) — Spectra Intelligence

> Query weekly malware family statistics by industry category using Spectra Intelligence tca-0307 to tca-0311 and tca-0317 — APT, Financial, Ransomware, Retail, and CVE.

ReversingLabs Malware Detection Family Feed V2 provides information about new malware samples detected in the Spectra Intelligence system, filtered by category (industry). Categories and API codes correspond to ReversingLabs Targeted and Industry-Specific File Indicator Feeds (e.g., Financial, Retail, Exploits...).

To make sense of that data, ReversingLabs is creating weekly statistics and providing them via this API (Statistics API).

| Code     | Feed Name                                    |
|----------|----------------------------------------------|
| TCA-0307 | APT (Advanced Persistent Threats) Statistics |
| TCA-0308 | Financial Services Malware Statistics        |
| TCA-0309 | Retail Sector Malware Statistics             |
| TCA-0310 | Ransomware Statistics                        |
| TCA-0311 | CVE Exploits Statistics                      |
| TCA-0317 | Malware Configuration Statistics             |

**This API is rate limited to 1 request per second.**

## Feed Statistics Query

The following endpoints are supported:

**Fetch statistics for last week(s) - newly added**

This query returns a list of family names and the times when they were added to a particular category. The data is retrieved for up to last 30 weeks, or for all time since the data collecting started.

<Button title="View OpenAPI Specification" href="/SpectraIntelligence/API-reference/#tag/malware-hunting/get/apifeedmalwaredetectionfamilyv2statisticscategorycategoryfilter" />

### Request

```
GET /api/feed/malware/detection/family/v2/statistics/category/{category}/first_seen?[format=xml|json]&[all_time|weeks=0-30]
```

**Fetch statistics for last week(s) - unique counts**

This query returns the number of how many unique new samples were added to the statistics for each malware family in a given category. The data is retrieved for up to last 30 weeks, or for all time since the data collecting started.

```
GET /api/feed/malware/detection/family/v2/statistics/category/{category}/counts?[format=xml|json]&[all_time|weeks=0-30]
```

**Fetch statistics for last week(s) - top list**

This query returns family names together with their respective counts for the top 20 families in the requested number of weeks. Data for up to 30 latest weeks is available. It is also possible to request all-time top 20 families for the requested category.

```
GET /api/feed/malware/detection/family/v2/statistics/category/{category}/top_list?[format=xml|json]&[all_time|weeks=0-30]
```

-----------------------------------------------------------------------

The request and response formats are the same for all endpoints:

### Request

#### Path parameters

- `category`
  - Accepts one of the following: financial, retail, ransomware, apt, exploit, configuration
  - required
  - Categories correspond to ReversingLabs Targeted and Industry-Specific File Indicator Feeds. If there is no access to a category, or if a category does not exist, the response will be 403 Forbidden.

#### Query parameters

- `weeks`
  - The number of weeks for which the data will be retrieved. The value can be a number between 0 and 30.
  - When the parameter is not included in the request, defaults to 0 (which returns equal results as all_time).
  - If an integer from 1 to 30 is provided, then it will return the data for that many latest weeks.
  - optional
  - Items are included in the statistics based on the date when they were added to a particular category.
  - 30 is the maximum number of weeks for which it is guaranteed that the data is preserved.
  - The statistics will return either a list with data for each week (1-30), or a list with a single item stating that it represents all_time data.
- `format`
  - Allows choosing the response format. Accepts xml or json. When the parameter is not included in the request, defaults to xml
  - optional
- `all_time`
  - If this parameter is provided instead of weeks, returns statistics for all data since collecting started.
  - optional

### Response

Response example when `weeks=0`, or when using the `all_time` parameter

``` json
{
  "rl": {
    "feed": {
      "name": "string",
      "entries": []
    }
  }
}
```

-----------------------------------------------------------------------

`rl.feed.entries[]`

```json
{
  "all_time": true,
  "category": "string",
  "entries": []
}
```

- `all_time`
  - Indicates whether the response includes statistics for all time. Returns true if the optional all_time parameter was included in the request
- `week`
  - Indicates the week number for which statistics are returned. It is not included in the response if the request contained the all_time parameter.
  - The format is ISO week number YYYY-Ww. For example, week 30 in 2018 would be “2018-W30”
- `category`
  - Indicates the category for which statistics are returned

-----------------------------------------------------------------------

`rl.feed.entries[].entries[]`

```json
{
  "family_name": "string",
  "first_seen": "string",
  "scanner_coverage": {
    "entries": [
      {
        "percent": 0.0,
        "name": "string"
      }
    ]
  }
}
```

- `family_name`
  - Malware family name of the detected malware
- `count`
  - The number of unique occurrences of this family name in a given category
- `first_seen`
  - Date and time when the item was first seen (UTC)
- `scanner_coverage`
  - Returned only for the exploit category.
  - For every item in the statistics, includes percent and name fields. Names correspond to antivirus scanners which were used to scan the sample. Percentage indicates how confident a specific scanner is that the particular sample belongs to an exploit family.

## Examples

### Request Examples

**Fetching the latest counts for apt and exploit categories in JSON format:**

```
/api/feed/malware/detection/family/v2/statistics/category/apt/counts?format=json&weeks=1
/api/feed/malware/detection/family/v2/statistics/category/exploit/counts?format=json&weeks=1
```

**Fetching the all-time top list for apt, exploit and financial categories in XML format:**

```
/api/feed/malware/detection/family/v2/statistics/category/apt/top_list
/api/feed/malware/detection/family/v2/statistics/category/exploit/top_list?format=xml&all_time
/api/feed/malware/detection/family/v2/statistics/category/financial/top_list?format=xml&weeks=0
```

**Fetching families added in the last 3 weeks for retail and financial categories in JSON format:**

```
/api/feed/malware/detection/family/v2/statistics/category/retail/first_seen?format=json&weeks=3
/api/feed/malware/detection/family/v2/statistics/category/financial/first_seen?format=json&weeks=3
```

### Response Examples

``` json
{
  "rl": {
    "feed": {
      "name": "Verticals Statistics Top List",
      "entries": [
        {
          "all_time": true,
          "category": "apt",
          "entries": [
            {
              "count": 1229365,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 786435,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 219329,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 115916,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 76910,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 10765,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 10386,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 4957,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 3089,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 2847,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 2300,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 1109,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 989,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 755,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 608,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 603,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 445,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 423,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 315,
              "family_name": "FAMILY_NAME"
            },
            {
              "count": 268,
              "family_name": "FAMILY_NAME"
            }
          ]
        }
      ]
    }
  }
}
```

``` json
{
  "rl": {
    "feed": {
      "name": "Verticals Statistics Top List",
      "entries": [
        {
          "category": "exploit",
          "all_time": true,
          "entries": [
            {
              "count": 132278,
              "family_name": "CVE-2008-2992",
              "scanner_coverage": {
                "entries": [
                  {
                    "percent": 95.013291846660422,
                    "name": "SCANNER_NAME"
                  },
                  {
                    "percent": 97.528924870857622,
                    "name": "SCANNER_NAME"
                  },
                  {
                    "percent": 95.035948403467955,
                    "name": "SCANNER_NAME"
                  },
                  {
                    "percent": 94.961936984563337,
                    "name": "SCANNER_NAME"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  }
}
```

``` json
{
  "rl": {
    "feed": {
      "name": "Verticals Statistics First Seen",
      "entries": [
        {
          "week": "2017-W20",
          "category": "exploit",
          "entries": [
            {
              "family_name": "FAMILY_NAME",
              "first_seen": "2017-05-15 00:58:12"
            },
            {
              "family_name": "FAMILY_NAME",
              "first_seen": "2017-05-15 14:13:35"
            },
            {
              "family_name": "FAMILY_NAME",
              "first_seen": "2017-05-15 20:21:40"
            }
          ]
        },
        {
          "week": "2017-W21",
          "category": "exploit",
          "entries": [
            {
              "family_name": "FAMILY_NAME",
              "first_seen": "2017-05-25 20:40:07"
            },
            {
              "family_name": "FAMILY_NAME",
              "first_seen": "2017-05-23 22:03:20"
            },
            {
              "family_name": "FAMILY_NAME",
              "first_seen": "2017-05-25 16:23:07"
            }
          ]
        }
      ]
    }
  }
}
```
