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:
| 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:
| 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:
| 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:
- Navigate to your PhishER Inbox.
- Enter your query string in the Search… bar in the top-left corner of the page.
- Press the Enter key or the Return key on your keyboard.
To run a query from the PhishRIP Queries page, follow the steps below:
- Navigate to PhishRIP.
- Enter your query string in the Search… bar in the top-left corner of the page.
- 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. |