Search Indicators¶

POST /1.3/indicators/search

Note

This endpoint can also be used to browse through indicators, by not applying a search term.

Warning

Can page through maximum of 10,000 IOCs for a single search. A “500” error will occur when attempting to request the page number after the page that the 10,000th IOC is on. If a query might yield more than 10k IOCs, break it into multiple smaller queries.

Warning

Time ranges are limited to 1 year maximum. To search time ranges larger than 1 year, run multiple searches.

Description¶

Searches for all indicators that contain the given search term. Also allows filtering by date, enclave, type, and tags. Results are ordered by last seen time, descending.

Parameters¶

Note: Only the searchTerm can be given either as a query string parameter (e.g. POST /indicators/search?searchTerm=test) or in the JSON body of a POST request (e.g. POST /indicators/search {"searchTerm": "abc"}). Other parameters should be passed as query string parameter.

Parameter	Default	Description
searchTerm		The string to search for, must be at least 3 characters in length. If empty or less than 3 characters, no search term will be applied, and all indicators matching the other filters will be returned.
enclaveIds	All enclaves the user has `READ` access to.	comma-separated list of enclave ids; only indicators found in reports from these enclaves will be returned (defaults to all of user’s enclaves)
entityTypes	All entity types.	comma-separated list of entity/indicator types to filter by. See “Indicator Types” on the Indicator page for the list of available indicator/entity types.
from	see table below.	start of time window (Unix timestamp, milliseconds since epoch). Values more than 1 year before `to` will be truncated to reduce the time range to a max size of 1 year.
to	see table below.	end of time window (Unix timestamp, milliseconds since epoch)
tags		a list of names of tags to filter by; only indicators containing ALL of these tags will be returned
excludedTags		indicators containing ANY of these tags will be excluded from the results.
pageNumber	0	which page of the result set to get. Careful to not page past result 10,000.
pageSize	100	The number of results per page. Max allowed size is 1000.

Searching vs. Scrolling¶

all = all IOCs that match other filter criteria (tags/type/enclaves)

matches = searchTerm string matches that also match other filters (tags/type/enclaves)

searchTerm	from	to	Behavior
			all; now - 24hrs < lastSeen < now.
	y		all; “from” < lastSeen < “from” + 24hrs.
		y	all; “to” - 24hours < lastSeen < “to”.
	y	y	all; “from” < lastSeen < “to”. If (“from” → “to”) > 1 year, “from” auto-adjusted to “to - 1 year”.
y			matches; now - 1year < lastSeen < now.
y	y		matches; “from” < lastSeen < “from” + 24hrs.
y		y	matches; “to” - 24hrs < lastSeen < “to”.
y	y	y	matches; “from” < lastSeen < “to”. If (“from” → “to”) > 1 year, “from” auto-adjusted to “to - 1 year”.

Response (200)¶

A page of Indicator objects.

Note

priorityLevel is present in the response but is deprecated.

Example Usage: Searching¶

Request¶

curl -k -H "Authorization: Bearer {access_token}" \
   -H "Content-Type: application/json" \
   -d '{"searchTerm": "172.68.11"}'  \
   -X POST "https://api.trustar.co/api/1.3/indicators/search"

Response¶

{
   "pageNumber":0,
   "totalPages":1,
   "pageSize":100,
   "totalElements":4,
   "items":[
      {
         "indicatorType":"CIDR_BLOCK",
         "value":"172.68.11.219/32",
         "priorityLevel":"NOT_FOUND",
         "guid":"CIDR_BLOCK|172.68.11.219/32",
         "firstSeen": 1610726516000,
         "lastSeen": 1623772916000
      },
      {
         "indicatorType":"IP",
         "value":"172.68.11.219",
         "priorityLevel":"NOT_FOUND",
         "guid":"IP|172.68.11.219",
         "firstSeen": 1610726516000,
         "lastSeen": 1623772916000
      },
      {
         "indicatorType":"IP",
         "value":"172.68.11.231",
         "priorityLevel":"NOT_FOUND",
         "guid":"IP|172.68.11.231",
         "firstSeen": 1610726516000,
         "lastSeen": 1623772916000
      },
      {
         "indicatorType":"IP",
         "value":"172.68.11.17",
         "priorityLevel":"NOT_FOUND",
         "guid":"IP|172.68.11.17",
         "firstSeen": 1610726516000,
         "lastSeen": 1623772916000
      }
   ],
   "empty":false,
   "hasNext":false
}

Example Usage: Scrolling¶

Request¶

curl -k -H "Authorization: Bearer {access_token}" \
   -H "Content-Type: application/json" \
   -X POST "https://api.trustar.co/api/1.3/indicators/search"

Response¶

{
   "pageNumber":0,
   "totalPages":69735,
   "pageSize":100,
   "totalElements":6973492,
   "items":[
      {
         "indicatorType":"IP",
         "value":"45.159.255.255",
         "priorityLevel":"NOT_FOUND",
         "guid":"IP|45.159.255.255",
         "firstSeen": 1610726516000,
         "lastSeen": 1623772916000
      },
      {
         "indicatorType":"URL",
         "value":"https://apps.db.ripe.net/search/query.html",
         "priorityLevel":"NOT_FOUND",
         "guid":"URL|https://apps.db.ripe.net/search/query.html",
         "firstSeen": 1610726516000,
         "lastSeen": 1623772916000
      },
      {
         "indicatorType":"URL",
         "value":"http://e9.keff.org/",
         "priorityLevel":"NOT_FOUND",
         "guid":"URL|http://e9.keff.org/",
         "firstSeen": 1610726516000,
         "lastSeen": 1623772916000
      },

      [ ***100 Indicator resources in this list*** ]

   ],
   "empty":false,
   "hasNext":true
}