Reputation v2 Scores

The reputation service regularly calculates a final reputation score for every active indicator and stores these scores in its database. This process supports multiple algorithms and will calculate a score for each of them. Additionally, it fetches any overrides which cover the indicator and calculates an overridden score if there exist matching overrides. All scores are stored by the reputation service and are available through the REST API.

Currently, the service has implemented the following algorithms:

• maxConfidence (production): It calculates the reputation score of an indicator based on the confidence of the indicator lists. It finds max(confidence) from all indicator lists.

• decreasingRelevancyMaxConfidence (experimental): It uses the same basic scoring than maxConfidence. In addition, it decreases the score stepwise based on the age of the indicator until a minimum score is reached. How fast the score decreases depends on the indicator type, e.g. IP addresses decrease quicker than domains. The reason is that IP addresses change more quickly and therefore decrease in relevancy faster.

More algorithms might be added in the future. Users can select which score is returned by specifying the scoringAlgorithm parameter in the request.

Response model

The following shows an example of a calculated score. The scoringMethod field specifies whether the score is calculated or overridden, and the scoringAlgorithm field specifies the algorithm used for scoring. Additionally, calculationDetails gives an overview of the indicator lists which contributed to the score, i.e. lists containing active indicators for the given value.

{
    "type": {
      "shortName": "domain",
      "name": "Domain"
    },
    "value": "evil.example.org",
    "score": 0.3,
    "scoringAlgorithm": "maxConfidence",
    "scoringMethod": "calculated",
    "scoringTimestamp": 1777030801788,
    "calculationDetails": {
      "contributingIndicatorLists": [
        {
          "id": "7ee84014-1d62-4146-b185-4ce729f7bfb4",
          "shortName": "myindicatorlist",
          "name": "My indicator list",
          "confidence": 0.3
        }
      ]
    },
    "overrideDetails": null,
    "flags": []
}

This is an example of an overridden score. The overrideDetails field contains the overrides which cover the indicator. The final score is max(score) from all overrides.

{
    "type": {
      "shortName": "domain",
      "name": "Domain"
    },
    "value": "www.vg.no",
    "score": 0,
    "scoringAlgorithm": "maxConfidence",
    "scoringMethod": "overridden",
    "scoringTimestamp": 1777030801782,
    "calculationDetails": null,
    "overrideDetails": {
      "contributingOverrides": [
        {
          "id": "6c166338-d07a-46ac-9a5c-da36a61aef50",
          "type": {
            "shortName": "domain",
            "name": "Domain"
          },
          "value": "vg.no",
          "score": 0,
          "reason": "VG is a respected news page in Norway."
        }
      ]
    },
    "flags": []
}

Note that the requesting user might not have access to some of the underlying data of the score, i.e. indicator lists or overrides. Therefore, non-accessible indicator lists and overrides are filtered out. If this is the case the response will contain the redacted flag. A user must have access to at least one indicator list which contributed to the score to be able to view the score of an indicator.

API endpoints

Fetch a single reputation score

The following request fetches the reputation score for the indicator evil.example.org. Specify scoringAlgorithm as a query parameter to select the algorithm used for the returned score.

curl -X GET 'https://api.mnemonic.no/reputation/v2/score/domain/evil.example.org' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Argus-API-Key: my/api/key'

Search reputation scores

This endpoint allows the user to search for reputation scores and filter the returned data. For example, the following request lists 100 reputation scores of type domain.

curl -X POST 'https://api.mnemonic.no/reputation/v2/score/search' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "type": [ "domain" ],
  "limit": 100
}'

This endpoint only allows to paginate up to 10.000 elements using limit and offset. In order to paginate beyond 10.000 elements use afterValue plus sorting by value. Do not filter on afterValue in the first request. In subsequent requests set afterValue to the value field from the last element in the previous response. This will request the next page of elements. Repeat until no more data is returned.

List reputation scores

This is a simplified version of the search endpoint with limited options.

curl -X GET 'https://api.mnemonic.no/reputation/v2/score' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Argus-API-Key: my/api/key'