Reputation Integration Guide#

Overview#

Tip

The Swagger API documentation is always up-to-date and lets you try out any query with your user session or an API-key.

The Reputation Service allows for the submission and retrieval of Domain and IP observations. These Observations can be retrieved directly or via filtered searches.

These Observations can be aggregated to return a quantitative calculated reputation for IPs or Domains. This reputation score can be used, for example, to filter and/or enrich event logs.

The Reputation API provides endpoints for

  • submitting IP/domain observations from pre-configured sources

  • retrieving individual observations

  • searching for sets of matching observations

  • managing override lists to handle matching IPs/domains

  • managing reputation sources and roles

  • calculating reputation values for arbitrary and specific IPs/domains

Concepts#

Source

A verified actor reporting observations of IPs and/or Domains.

Role

The type of host identified by the observed IP or Domain.

Override

Rules for white/gray/blacklisting of matching IPs and Domains that can override the Source’s default properties.

Observation

Information from a Source about a specific IP or Domain.

Calculated Reputation

A reputation score for a specific IP or Domain. Can be used e.g. for assessing event severity.

Detailed API documentation#

The Swagger API documentation is always up-to-date and lets you try out any query with your user session or an API-key.

Managing Sources#

We cannot submit Observations without indicating which Source made the Observation.

Either we add Observations from an existing Source or we need to create a new one, with a unique alias.

Tip

NB: if a Source is marked private then the user creating/updating/fetching it or attempting to view observations made it must have the appropriate permission to view private observation data

Creating Sources#

To create a new Source you must ensure the following

  • you have the appropriate permission(s) to modify public/private observation data, depending on the type of Source

  • its name and alias are not blank and the alias is unique i.e. another Source with the same alias does not already exist

  • the Source’s confidence level is between 0.0 and 1.0

  • the Source’s fudge and active periods, in milliseconds, must be at least 1 hour i.e. >= 3600000

curl -X 'POST' \
  'https://devapi.mnemonic.no/reputation/v1/source' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Argus-API-Key: my/api/key' \
  -d '{
  "private": true,
  "alias": "DemoSource",
  "name": "DemoSource",
  "confidence": 0.5,
  "activePeriod": 3600000,
  "fudgePeriod": 3600000,
  "useForReputationCalc": true,
  "enableSync": true,
  "monitored": true
}'

Retrieving Sources#

We can retrieve existing Sources by their numerical ID or alias.

curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/source/aliasOrID

The requesting user must have the appropriate permission to view observation data.

We can also search for Sources by their id, alias, and name fields.

curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/reputation/v1/source/search -d '{
    "searchString": "alias or name",
    "id": "1",
    "includeDeleted": "true"
}'

Updating Sources#

When updating/transitioning a Source identified by its id or alias we can change all the fields we are able to set upon creation, including alias.

The same permissions and field specific validation requirements apply.

In addition, we can optionally change a Source’s properties to indicate whether

  • it is monitored

  • its observations may be used for performing reputation calculations

  • its observations will be synced to Argus’ distributed nodes

curl -X PUT -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/reputation/v1/source/1 -d '{
  "alias": "newUniqueAlias",
  "name": "newNonUniqueName",
  "private": false,
  "confidence": 0.1,
  "activePeriod": 7200000,
  "fudgePeriod": 7200000,
  "useForReputationCalc": true,
  "enableSync": true,
  "monitored": true
}'

Transitioning Sources#

This recalculates active and expired Observations for a given Source. By default, a Source is transitioned after completing an import.

curl -X PUT -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/source/1/transition -d {}

Deleting/Restoring Sources#

Sources can be deleted by id, assuming the requesting user has the appropriate permission to edit observation data.

curl -X DELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/source/1

Upon deletion a Source is not removed from the underlying data stores but rather simply flagged as deleted.

By default, deleted Sources are not including in search results.

A deleted Source can also be restored to remove the deleted flag.

curl -X PUT -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/source/1/restore -d {}

Managing Roles#

Similar to Sources, when submitting Observations we must specify the host’s Role, identified by its unique alias.

If an appropriate one does not already exist then we can create a new one.

Creating Roles#

To create a new Role you must ensure the following

  • you have the appropriate permission(s) to modify public/private observation data, depending on the type of Source

  • its name and alias are not blank and the alias is unique i.e. another Role with the same alias does not already exist

  • the Role’s score must be between 0.0 and 1.0

curl -X 'POST' \
  'https://devapi.mnemonic.no/reputation/v1/role' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Argus-API-Key: my/api/key' \
  -d '{
  "alias": "DemoRole",
  "name": "DemoRole",
  "score": 0.5
}'

Retrieving Roles#

We can retrieve existing Roles by their numerical ID or alias.

curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/role/aliasOrID

The requesting user must have the appropriate permission to view observation data.

We can also search for Roles by their id, alias, and name fields.

curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/reputation/v1/role/search -d '{
    "searchString": "alias or name",
    "id": "1",
    "includeDeleted": "true"
}'

Updating Roles#

When updating a Role identified by its id or alias we can change all the fields we are able to set upon creation, including alias.

curl -X PUT -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/reputation/v1/role/1 -d '{
  "alias": "newUniqueAlias",
  "name": "newNonUniqueName",
  "score": "0.1"
}'

The same permissions and field specific validation requirements apply.

If the Role was deleted then updating it will additionally restore it and remove the deleted flag.

Deleting/Restoring Roles#

Roles can be deleted by id, assuming the requesting user has the appropriate permission to edit observation data.

curl -X DELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/role/1

Upon deletion a Role is not removed from the underlying data stores but rather simply flagged as deleted.

By default, deleted Role are not including in search results.

A deleted Role can also be restored to remove the deleted flag.

curl -X PUT -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/role/1/restore -d {}

Managing Overrides#

An Override tells the Reputation Service to score Observations for domains and IPs matching the Override differently than the default value for their Source/Role.

Overrides are collected into Override Lists, which can define whether member Overrides are to be used when calculating reputation values or filtering events.

Creating Override Lists#

Override Lists must have a description and unique name i.e. another Override List with the same name must not be present, active or otherwise.

To create an Override List the user must have the appropriate permission to edit Override data.

When creating an Override we can optionally set the following flags

  • useForReputationCalc - if true the scores for member Overrides will be used for matching Observations when calculating reputation values for a given IP or Domain

  • useForInputFiltering - if true use the member Overrides’ scores for matching Observations when filtering Events/Observations

  • useForDefaultValues - if true use the scores for member Overrides when ingesting matching Observations rather than the Observations’ Role/Source’s score

curl -X 'POST' \
'https://devapi.mnemonic.no/reputation/v1/override/list' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Argus-API-Key: my/api/key' \
-d '{
  "name": "DemoOverrideList",
  "description": "Used for demonstrating Overrides",
  "useForReputationCalc": true,
  "useForInputFiltering": false,
  "useForDefaultValues": false
}'

Retrieving Override Lists#

Assuming the appropriate permission to view Override data a user can retrieve specific Override Lists by their id.

curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/override/list/1

Alternatively there is an endpoint to retrieve all active Override Lists, filtered by Override List names.

curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/override/list?keywords=listName

Updating Override Lists#

When updating an Override List, identified by its id, we can modify all fields including the name and the optional flags.

curl -X 'PUT' \
'https://devapi.mnemonic.no/reputation/v1/override/list/1' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Argus-API-Key: my/api/key' \
-d '{
  "name": "New Unique Override List Name",
  "description": "New description",
  "useForReputationCalc": true,
  "useForInputFiltering": false,
  "useForDefaultValues": false
}'

The new name must still be unique i.e. another Override List with the same name must not exist.

Deleting Override Lists#

We can delete an existing Override List by its id.

curl -X DELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/override/list/1

It must already be empty i.e. not contain any Overrides.

We can remove existing Overrides identified by their id from a list either individually:

curl -X DELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/override/ip/1
curl -X DELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/override/domain/1

Or in batches:

curl -X DELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/override/ip?id=1&id=2
curl -X DELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/override/domain?id=1&id=2

Once an Override List is flagged as deleted there is currently no way to restore it.

Creating Overrides#

On creation Overrides must be added to an existing Override List, identified by its id or name.

The Override must contain

  • either an IPRange or Domain Pattern depending on the type of override

  • the value, between 0 and 1.0, for the Override

  • the reason why the Override was created

  • a cutoff/expiry timestamp for the Override

We can also optionally clear the target Override List of all existing entries when adding the Override.

curl -X 'POST' \
'https://devapi.mnemonic.no/reputation/v1/override/ip' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Argus-CSRF-Token: tokenGoeshere' \
-d '{
  "listName": "IPOverrides",
  "clear": false,
  "overrides": [
    {
      "ipRange": "182.237.2.160-182.237.2.254",
      "value": 0.1,
      "reason": "Known customer network",
      "cutoff": 0
    }
  ]
}'

Retrieving Overrides#

Assuming the user has the appropriate permission to view Override data they can retrieve a specific Override entry by its id.

curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/override/ip/1
curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/override/domain/1

We can also search for Override entries by matching IPRange or Domain pattern or their Override List’s metadata.

curl -X 'POST' \
'https://devapi.mnemonic.no/reputation/v1/override/ip/search' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Argus-CSRF-Token: tokenGoeshere' \
-d '{
  "listName": [ "OtherIPOverrides", "IPOverrides" ],
  "ranges": [ "192.168.123.24" ]
}'

curl -X 'POST' \
'https://devapi.mnemonic.no/reputation/v1/override/domain/search' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Argus-CSRF-Token: tokenGoeshere' \
-d '{
  "listName": [ "OtherIPOverrides", "IPOverrides" ],
  "domainPatternBases": [ "mnemonic.no" ]
}'

For the full list of supported search criteria please refer to the Swagger API documentation

Removing Overrides#

The service currently does not support updating Overrides.

Rather, we can remove existing Override entries, identified by their id, from a list.

curl -X DELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/override/ip/1
curl -X DELETE -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/override/domain/1

This will additionally flag the Overrides as deleted.

There is currently no way of restoring a removed/deleted Override entry.

Calculated Reputations#

One of the primary purposes of the Reputation Service is to provide other services a reputation score for a given IPRange or Domain.

A common use case is when processing events we might want to set filtering thresholds for events associated with IPRanges and Domains with a certain reputation score.

IP Reputations#

We can retrieve reputation for a specific IP

curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/calculated/ip/192.168.124.22

We can also use list reputations for matching IPs filtered by

  • inclusive fromAddress

  • exclusive afterAddress

  • the observations’ source sourceID

  • minimum reputation score minimumValue

curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/calculated/ip?fromAddress=192.168.124.22&sourceID=1&minimumValue=0.5

In addition to the basic GET endpoint there is a dedicated search endpoint that, in addition to these query parameters, supports

  • exact matching on IP addresses

  • advanced sub-criteria based logic

  • sorting

Both endpoints support paginating via the limit and offset params.

Please refer to the Swagger API documentation for the full list of supported search criteria and options.

Domain Reputations#

We can retrieve reputation for a specific Domain

curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/calculated/domain/mnemonic.no

We can also list reputations for matching domains filtered by

  • inclusive fromDomain

  • exclusive afterDomain

  • the observations’ source sourceID

  • minimum reputation score minimumValue

curl -H "Argus-API-Key: my/api/key" https://api.mnemonic.no/reputation/v1/calculated/domain?fromDomain=192.168.124.22&sourceID=1&minimumValue=0.5

In addition to the basic GET endpoint there is a dedicated search endpoint that, in addition to these query parameters, supports

  • exact matching on domains

  • advanced sub-criteria based logic

  • sorting

Both endpoints support paginating via the limit and offset params.

Please refer to the Swagger API documentation for the full list of supported search criteria and options.