What is Lucene Query Syntax?
Lucene is a query language that can be used to filter messages in your PhishER inbox. A query written in Lucene can be broken down into three parts:
- Field The ID or name of a specific container of information in a database. If a field is referenced in a query string, a colon ( : ) must follow the field name.
- Terms Items you would like to search for in a database. You can search for Single Terms ("Hello") and Phrases ("Hello world"). A term does not have to be enclosed in quotation marks.
- Operators/Modifiers A symbol or keyword used to denote a logical operation.
Operator/Modifier Meaning AND Both input parameters return TRUE. OR Only one input parameter returns TRUE. NOT The input parameter returns FALSE. NOT can also be represented using the ( - ) symbol. * Wildcard that is a placeholder for multiple characters. ? Wildcard that is a placeholder for a single character. This wildcard cannot be used as a placeholder for the first character of a string.
To create a query, you can use the field, term, and operator/modifier to form a string. Below is an example of how a Lucene query string is constructed:
field_name: "This is the phrase I want to search for!" AND "This"
The field referred to in your string must match a field acknowledged in the database you are running a query against.
What Fields Can I Reference in a Query?
Below is a table of all the fields you may reference when filtering your PhishER inbox through search queries.
|Field Name||Use Case||Example|
|attachment_names||Use this field to filter messages by file name or extension type.||attachment_names: "inv.pdf"
|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"
|hosts||Use this field to filter messages by the hostname(s) tied to the message.||hosts: "knowbe4.com"
|reported_at||Use this field name to search for messages reported on a specific date.
The following date format is acceptable:
|reported_by||Use this field to filter messages by the email address of the reporter.||reported_by: "@knowbe4.com"|
|reported_by_name||Use this field to filter messages by the name of the reporter. Note: 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. See reported_at for the acceptable date format.||sent_at: "2018-12-04"|
|subject||Use this field to filter messages by the subject line of the message.||subject: "invoice"
|tags||Use this field to filter messages by the tags attached to it.||tags: "threat"
|to||Use this field to filter messages by the email address the message was originally sent to.||to: "@knowbe4.com"
|urls||Use this field to filter messages by URLs found in the message.||urls: "knowbe4.com"
How Do I Run a Query in PhishER?
To run a query in PhishER, navigate to PhishER > Inbox. Then, type your query string in the Search... bar in the top-left.
Query strings will vary depending on the intended goal of your search. Below are example query strings you may customize and run in your PhishER inbox.
This query will pull all messages tagged as a threat with "urgent" or "immediately" in the subject line:
tags: "threat" AND (subject: "urgent" OR "immediately")
Replace your-organization-domain.com with your organization's domain. Then, this query will pull all messages that are NOT sent from your domain:
NOT from_name: your-organization-domain.com
This query will pull all messages with words or phrases starting with "network" in the subject line and NOT tagged as spam:
subject: "network*" AND -tag: "spam"
This is a brief overview of Lucene query syntax to get you started with custom searches in your PhishER inbox. Visit here for full Lucene query syntax documentation.