Reputation v2 Indicators#

Indicators are the individual IoCs reported by reputation indicator lists. They can be fetched by ID, listed with common filters, searched by exact type/value or searched with advanced domain-specific and IP-specific criteria.

Concepts#

Indicator states#

Indicators can be in one of three states: active, latest and old. By default, the search endpoints only return active indicators.

When an indicator is imported, it is stored as active if its lastSeenTimestamp is inside the indicator list’s active period. Otherwise, it is stored as latest. During indicator list transition, active indicators outside the active period are moved to latest, and latest indicators inside the active period are moved back to active.

If an existing active or latest indicator is imported again inside the indicator list’s grace period, the existing indicator is updated. If it is imported again outside the grace period, the existing indicator is moved to old and a new indicator is created.

Access control#

To view indicators in Argus, the user needs to be granted the viewReputationIndicators Argus function. Additionally, only indicators from indicator lists where the user has access to the configured read function will be returned.

Indicator properties are only returned when explicitly requested. To include properties, the user must have access to the requested property descriptor’s view permission. This access is configured per property descriptor with its own read function.

Indicator values#

The simple type/value endpoint and the value field in the advanced search request match exact indicator values.

For domain indicators, the advanced search endpoint can also include parent domains and subdomains. For example, a search for www.vg.no can also return vg.no, and a search for vg.no can also return www.vg.no.

For IP indicators, the advanced search endpoint supports single IPv4/IPv6 addresses, CIDR notation and IP ranges.

Response model#

The following shows an example indicator response. The indicatorList field contains compact information about the list which reported the indicator. The properties field is only populated when properties are requested with includeProperties.

{
  "id": "15ab1f7b-a032-47d9-97a2-97871fb2f9b4",
  "indicatorList": {
    "id": "7ee84014-1d62-4146-b185-4ce729f7bfb4",
    "shortName": "myindicatorlist",
    "name": "My indicator list",
    "confidence": 0.5
  },
  "type": {
    "shortName": "domain",
    "name": "Domain"
  },
  "value": "evil.example.org",
  "firstSeenTimestamp": 1777030801788,
  "lastSeenTimestamp": 1777030801788,
  "state": "active",
  "createdTimestamp": 1777030801788,
  "lastUpdatedTimestamp": 1777030801788,
  "deletedTimestamp": 0,
  "flags": [],
  "properties": []
}

Requested indicator properties are returned with descriptor information and either value or values, depending on whether the property is single-valued or multivalued.

{
  "descriptor": {
    "id": "6ea057c2-798c-48fc-9f98-8be1b51a0eb4",
    "name": "Comment",
    "shortName": "comment"
  },
  "dataType": "fullText",
  "multiValue": false,
  "value": "Imported from external feed",
  "values": null
}

Listing indicator types#

  • GET /reputation/v2/type

Lists all available indicator types, sorted by shortName. Use this endpoint to discover valid type values for indicator search endpoints, for example domain or ip.

Access Control#

To list indicator types in Argus, the user needs to be granted the viewReputationIndicatorTypes Argus function.

Example#

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

Fetching an indicator#

  • GET /reputation/v2/indicator/{id}

Fetches one indicator by its UUID.

Access Control#

To fetch an indicator in Argus, the user needs to be granted the viewReputationIndicators Argus function. Additionally, the user needs access to the read function configured on the indicator’s indicator list.

If includeProperties is used, the user must also have access to the requested property descriptors. This access is configured per property descriptor with its own read function.

Parameters#

Supported query parameters:

  • includeProperties: Property descriptor IDs or short names to include in the response.

Example#

curl -X GET 'https://api.mnemonic.no/reputation/v2/indicator/15ab1f7b-a032-47d9-97a2-97871fb2f9b4' \
  -H 'accept: application/json' \
  -H 'Argus-API-Key: my/api/key'

Include selected properties:

curl -X GET 'https://api.mnemonic.no/reputation/v2/indicator/15ab1f7b-a032-47d9-97a2-97871fb2f9b4?includeProperties=comment&includeProperties=role' \
  -H 'accept: application/json' \
  -H 'Argus-API-Key: my/api/key'

Listing indicators#

  • GET /reputation/v2/indicator

This is a simplified version of the search endpoint with common filters available as query parameters. By default, it returns 25 active indicators sorted by newest lastUpdatedTimestamp first.

Access Control#

To list indicators in Argus, the user needs to be granted the viewReputationIndicators Argus function. Additionally, only indicators from indicator lists where the user has access to the list’s read function will be returned.

Parameters#

Supported query parameters:

For parameters that accept multiple values, add the parameter once for each value, e.g. state=active&state=latest.

  • offset: Number of results to skip. Defaults to 0.

  • limit: Number of results to return. Defaults to 25.

  • sortBy: Sort field. Prefix with - for descending order. Accepts multiple values. Defaults to -lastUpdatedTimestamp.

  • indicatorList: Indicator list IDs or short names to search in. Accepts multiple values.

  • includeProperties: Property descriptor IDs or short names to include in each response. Accepts multiple values.

  • value: Exact indicator values to search for. Accepts multiple values.

  • type: Indicator type short names to search for. Accepts multiple values.

  • state: Indicator states to return: active, latest, old. Accepts multiple values. Defaults to active.

Supported sort fields are indicatorList, type, value, createdTimestamp, lastUpdatedTimestamp and deletedTimestamp.

Example#

curl -X GET 'https://api.mnemonic.no/reputation/v2/indicator?indicatorList=myindicatorlist&state=active&limit=100&sortBy=-value' \
  -H 'accept: application/json' \
  -H 'Argus-API-Key: my/api/key'

Include multiple states and properties:

curl -X GET 'https://api.mnemonic.no/reputation/v2/indicator?state=active&state=latest&includeProperties=comment&includeProperties=role' \
  -H 'accept: application/json' \
  -H 'Argus-API-Key: my/api/key'

Listing indicators for one value#

  • GET /reputation/v2/indicator/{type}/{value}

Lists indicators matching one exact indicator type and value. Use this endpoint to find every stored indicator record for one IoC, optionally restricted by indicator list or state.

This endpoint uses exact value matching. It does not apply the domain parent/subdomain logic or the IP range/CIDR logic from the advanced search endpoint.

Access Control#

To list indicators in Argus, the user needs to be granted the viewReputationIndicators Argus function. Additionally, only indicators from indicator lists where the user has access to the list’s read function will be returned.

Parameters#

Path parameters:

  • type: Indicator type short name, for example domain or ip.

  • value: Exact indicator value.

Supported query parameters:

  • offset

  • limit

  • sortBy

  • indicatorList

  • includeProperties

  • state

Example#

curl -X GET 'https://api.mnemonic.no/reputation/v2/indicator/domain/evil.example.org?state=active&state=latest' \
  -H 'accept: application/json' \
  -H 'Argus-API-Key: my/api/key'

Search for an IP address in one indicator list:

curl -X GET 'https://api.mnemonic.no/reputation/v2/indicator/ip/192.0.2.10?indicatorList=myindicatorlist' \
  -H 'accept: application/json' \
  -H 'Argus-API-Key: my/api/key'

Searching for indicators#

  • POST /reputation/v2/indicator/search

This endpoint allows the user to search for indicators and filter the returned data. It supports all filters available in the simple list endpoints, plus confidence ranges, timestamp filters, deleted indicators, domain parent/subdomain matching, IP CIDR matching and IP range matching.

Access Control#

To search for indicators in Argus, the user needs to be granted the viewReputationIndicators Argus function. Additionally, only indicators from indicator lists where the user has access to the list’s read function will be returned.

If includeProperties is used, the user must also have access to the requested property descriptors. This access is configured per property descriptor with its own read function.

Parameters#

Available search terms:

  • indicatorList: Indicator list IDs or short names to search in.

  • type: Indicator type short names, for example domain or ip.

  • value: Exact indicator values to match.

  • domainSearch: Domain-specific search criteria.

  • ipSearch: IP-specific search criteria.

  • includeProperties: Property descriptors to include in each response.

  • state: Indicator states to return: active, latest, old. Defaults to active.

  • minConfidence: Minimum default confidence on the indicator list. Defaults to 0.

  • maxConfidence: Maximum default confidence on the indicator list. Defaults to 1.

  • startTimestamp: Start of timestamp filter. Supports unix timestamp in milliseconds, ISO timestamp or relative time. Defaults to 0.

  • endTimestamp: End of timestamp filter. Supports unix timestamp in milliseconds, ISO timestamp or relative time. Defaults to now.

  • timeFieldStrategy: Timestamp fields to filter. Defaults to all.

  • timeMatchStrategy: Whether timestamp filters must match all or any selected fields. Defaults to all.

  • includeDeleted: Include indicators flagged as deleted. Defaults to false.

  • offset: Number of results to skip. Defaults to 0.

  • limit: Number of results to return. Defaults to 25.

  • sortBy: Sort fields. Prefix with - for descending order. Defaults to -lastUpdatedTimestamp.

  • afterValue: Continue value-based pagination after this indicator value.

Supported timeFieldStrategy values are all, createdTimestamp, lastUpdatedTimestamp, deletedTimestamp, firstSeenTimestamp and lastSeenTimestamp.

Supported sort fields are indicatorList, type, value, createdTimestamp, lastUpdatedTimestamp and deletedTimestamp.

Example#

curl -X POST 'https://api.mnemonic.no/reputation/v2/indicator/search' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Argus-API-Key: my/api/key' \
  -d '{
  "type": ["domain"],
  "indicatorList": ["myindicatorlist"],
  "state": ["active", "latest"],
  "domainSearch": {
    "domain": ["evil.example.org"],
    "includeParentDomains": true,
    "includeSubdomains": false
  },
  "includeProperties": [
    { "descriptor": "comment" }
  ],
  "limit": 100,
  "sortBy": ["-lastUpdatedTimestamp"]
}'

Search by timestamp:

curl -X POST 'https://api.mnemonic.no/reputation/v2/indicator/search' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Argus-API-Key: my/api/key' \
  -d '{
  "startTimestamp": 1777027200000,
  "endTimestamp": 1777113600000,
  "timeFieldStrategy": ["firstSeenTimestamp", "lastSeenTimestamp"],
  "timeMatchStrategy": "any"
}'

This endpoint only allows pagination up to 10.000 elements using limit and offset. To paginate beyond 10.000 elements, define sortBy and use afterValue. The same sortBy value and the same filters must be used for every request while streaming the result set. 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.