Viewing Reported Emails

Share
Last updated:

Lucene Query Syntax Guide

Lucene is a query language that you can use to search for specific messages. You can use Lucene to run queries in your PhishER Inbox or on the PhishRIP Queries page.

This article is an overview of Lucene query syntax to help you get started with running custom queries in your PhishER platform. For more information, see Apache’s Lucene - Query Parser Syntax documentation.

Writing a Query

Lucene query syntax can be broken down into three parts: fields, terms, and operators or modifiers. You can use these strings to run queries, which allow you to search for messages from your PhishER Inbox and on the PhishRIP Queries page. You can use a combination of a field, term, and an operator or modifier to form a query string. Below is an example of a Lucene query string:

field_name: "This is the phrase I want to search for!" AND "This"

See the sections below to learn more about writing a query string using fields, terms, and operators or modifiers.

Fields

A field is the ID or name used to find specific information from a message. For example, you can use fields to filter messages by information such as who reported the email or when the email was reported. If a field is referenced in a query string, you must enter a colon ( : ) after the field name.

See the table below for a list of fields you can use in queries from your PhishER Inbox:

PhishER Inbox
Field Name Use Case Example
attachment_names Use this field to filter messages by file name or extension type.

attachment_names: "inv.pdf"

attachment_names: *.doc
cc Use this field to filter messages by an email address that was copied on the original message. cc: "@knowbe4.com"
from_name Use this field to filter messages by the sender name tied to the original message.

from_name: "CyberheistNews"

from_name: Cyberheist*
hosts Use this field to filter messages by the hostname(s) tied to the message.

hosts: "knowbe4.com"

hosts: *google.com
reported_at Use this field name to search for messages reported on a specific date.The following date format is acceptable:YYYY-MM-DD reported_at: "2018-11-27"
reported_by Use this field to filter messages by the reporter's email address. reported_by: *@knowbe4.com (http://knowbe4.com/)
reported_by_name

Use this field to filter messages by the reporter's name.

Important: This search is case-sensitive.
 reported_by_name: "First Last"
sent_at Use this field to filter messages by the date it was sent to the reporter. The following date format is accepted:YYYY-MM-DD

sent_at: "2018-12-04"

sent_at:[2020-03-03 TO *]

sent_at:[2020-03-03 TO 2020-04-04]

sent_at:[2020-03 TO 2020-04]
subject Use this field to filter messages by their subject lines.

subject: "invoice"

subject: immediate*
tags Use this field to filter messages by the tags attached to them. tags: "threat"-tags: "threat"
to Use this field to filter messages by the recipient's email address.

to: "@knowbe4.com"

to: *know*
urls Use this field to filter messages by URLs found in the message.

urls: "knowbe4.com"

urls:*

See the table below for a list of fields you can use in PhishER queries from the PhishRIP Queries page:

PhishRIP Queries
Field Name Use Case Example
source_id

Use this field to filter queries by the PhishER message used to initiate PhishRIP.

Note:You can view the message in the PhishER Inbox by navigating to the URL below. You will need to replace the source_id with the specific source ID for the message: https://phisher.knowbe4.come/inbox/source_id

source_id: "b039476c-7534-4d52-b162-b8058acbb1e0"

https://phisher.knowbe4.com/inbox/b039476c-7534-4d52-b162-b8058acbb1e0
id Use this field to search for an individual PhishRIP query. id: "98719b0a-b739-485f-98fe-6c343c21c27f"
started

Use this field to filter messages by the date when the query was created.

The following date format is acceptable: YYYY-MM-DD

 started:"2020-04-04"
originator Use this field to filter queries by the first and last name of a user who initiated PhishRIP. originator:"John Doe"

Terms

A term is a word or phrase that you can search for. You can search for two types of terms: Single Terms and Phrases. An example of a Single Term is "urgent," and an example of a Phrase is "action needed”. Terms do not have to be enclosed in quotation marks. You can combine multiple terms together with operators or modifiers to form a more complex query.

Operators and Modifiers

An operator or a modifier is a symbol or keyword that you can use to search for terms or exclude terms from your search.

See the table below for a list of operators or modifiers and their meanings:

Note: This list includes basic operators and modifiers. For a full list of operators and modifiers, see Apache’s Lucene - Query Parser Syntax documentation.
Operators and Modifier Description
AND You can use this option to find both terms that exist in the text of an email. You can use the && symbol instead of the word AND.
OR You can use this option to find at least one term that exists in the text of an email. You can use the || symbol instead of the word OR.
NOT You can use this option to exclude emails that contain the term after the word NOT. You can use the ! symbol or the - symbol instead of the word NOT.
*

You can use this wildcard placeholder for multiple characters. This placeholder can only be used with Single Terms.

Note: Wildcard placeholders cannot be used as the first character of a search.

For example, to search for need, needs, or needed, you can search for the following text:

need*
?

You can use this wildcard placeholder for a single character. This placeholder looks for terms that match but have a single character replaced.

For example, to search for a specific reporter, you can search for the following text:

reported_by: *@k?owbe4.com AND sent_at:[2020-03-03 TO *]

Running a Query

To run a query from your PhishER Inbox, follow the steps below:

  1. Navigate to your PhishER Inbox.
  2. Enter your query string in the Search… bar in the top-left corner of the page.
  3. Press the Enter key or the Return key on your keyboard. 

To run a query from the PhishRIP Queries page, follow the steps below:

  1. Navigate to PhishRIP.
  2. Enter your query string in the Search… bar in the top-left corner of the page.
  3. Press the Enter or the Return key on your keyboard. 

Once you've run the query, you can click its name to see the messages that were found.

Examples of Queries

Queries will vary depending on the information that you’re searching for. See the table below for examples of query strings that you can customize and run in your PhishER Inbox:

Query String Search Result
tags: "threat" AND (subject: "urgent" OR "immediately") This query will search for all messages tagged as a threat with "urgent" or "immediately" in the subject line.
-from_name: your-organization-domain.com

OR

NOT from_name: your-organization-domain.com 		This query will search for all messages that are not sent from your domain.Make sure to replace your-organization-domain.com with your organization's domain.
subject: "network*" AND -tag: "spam" This query will search for all messages with words or phrases that start with "network" in the subject line. Messages tagged as spam will not be included.

Was this article helpful?

8 out of 8 found this helpful