Hunting
On the Hunt page in the PolySwarm UI, we support Live and Historical Hunting using YARA Rulesets. A YARA Ruleset is a text file, traditionally having the .yar extension, that contains one or more YARA rules. Some people refer to the file as a YARA Rules file.
Yara Rules
When performing Live or Historical Hunting, Artifacts are processed by the YARA tool according to the YARA rules contained in the active YARA Ruleset. Writing YARA rules is explained in-depth in the YARA documentation. And there are example YARA Rules in the Yara-Rules GitHub repository.
Yara Rulesets are managed on the Hunt page’s Ruleset and Hunt Management tab.
Adding Rulesets
If you have not added any Rulesets, there is a large “Add Rulesets” button on the Rulesets and Hunt Management tab to add your first Ruleset. If you’ve already added one or more rulesets, there is a “+” button in the upper right to add additional Rulesets.
All Rulesets need a Name. The Description field is optional, but can be helpful to remember details about your rules. And finally there is the large text box to enter the YARA Rules.
You have 2 options to enter the Rules:
- You can paste your Rules into the large text box.
- You can click the small “+” button in the lower right corner of the large text box to select a YARA Ruleset file from your computer to upload as your Ruleset.
Click the Save button to save the Ruleset.
Validating Rulesets
When one or more Rules have been entered into the large Rules text box, the button in the bottom right changes from a “+” button to a “Validate” button. Click the Validate button to validate the syntax of your Ruleset. If you click outside of the Rules area after entering rules, the validation will automatically run for you. Once you have a valid Ruleset, click the Save button to save it.
Actions
Actions exist for each Ruleset, the following highlight the functionality of these options.
Viewing / Editing Rulesets
You can view and edit an existing Ruleset by clicking on the pencil icon in the Actions column. If you have a Live Hunt running, the pencil icon is disabled. You must stop the Live Hunt before you can edit the Ruleset.
Duplicating Rulesets
You can copy and duplicate an existing Ruleset by clicking on the copy icon in the Actions column. Clicking that icon will open the Create Ruleset window enabling you to create a new ruleset where the initial data is pre-filled using the data from this existing Ruleset. Make your changes, then click the Save button.
Deleting Rulesets
You can delete an existing Ruleset by clicking on the trash can icon in the Actions column, if the trash icon is disabled there is a Live Hunt running. If there is a running Live Hunt using this Ruleset, you must stop the Live Hunt before you can delete the Ruleset.
Running a Hunt using a Ruleset
You can start a Live Hunt using a Ruleset by simply clicking the toggle button to the "on" position. You can start a Historical Hunt using a Ruleset by clicking on the running man icon in the Actions column.
It is important to note that you cannot edit or delete a Ruleset while a Live Hunt is running. We store the contents of the Ruleset used at the time the Live or Historical Hunt is started. So when you view Hunt results, you are always able to reference the exact Ruleset that was used to run the Hunt.
Live Hunting
Live Hunting is a technique to use YARA Rules to examine new artifacts as they are submitted. When an artifact matches the Ruleset used in a Live Hunt, a new row is added to the Live Hunting Feed.
Viewing Live Hunting Matches
The Live Hunting Feed tab shows all Live Hunting matches as a continuous feed. The Live Hunt matches for all your active Live Hunts are displayed in the feed as a single listing in reverse chronological ordering.
Table of Matches
Each row in the table is a match for a Live Hunt. The row contains several key pieces of data and some Action buttons.
| Column | What is it for? |
|---|---|
| Checkboxes | Checking one or more of these boxes activates 2 buttons in the upper right.
|
| Rule Name | Column contains the name of the Rule that triggered the match. |
| SHA256 | Column is the SHA256 of the matching artifact. There is a copy icon that will copy the hash to your clipboard. |
| Malware Family Name | Column is the name of Malware Family associated with the artifact that matched the Rule. If the artifact was determined to be Benign, it is possible that the Malware Family name is blank. |
| PolyScore | Column shows the PolyScore for each match. |
| Detections | Column shows the number of malicious assertions / total assertions for the matched artifact. |
| Matched On | Is the date or relative time when the match happened. |
| Actions | Along the right side is the Actions column with several buttons.
|
Filter
In the upper right above the table is the Filter. You can define a Filter to limit the set of matches displayed in the table of matches. The Filter currently supports filtering by:
- Rule Name
- Malware Family Name
- PolyScore
Starting and Stopping a Live Hunt
You can start a Live Hunt using a Ruleset by simply clicking the toggle button to the "on" position. And stop it by toggling to the "off" position. Stopping a Live Hunt does NOT delete any of the matches from that Hunt. Live Hunt matches are always available in the Live Hunting Feed until you delete them.
Historical Hunting
Historical Hunting is a technique to use YARA Rules to examine artifacts that were submitted in the past. Currently, Historical Hunts evaluate all artifacts submitted over the past 6 months.
Viewing Historical Hunts
The Historical Hunts tab allows you to view/manage Historical Hunts and their Matches.
Each row in the table is a Historical Hunt. The row contains several key pieces of data about the Historical Hunt and some Action buttons.
| Column | What is it for? |
|---|---|
| Checkboxes | Checking one or more of these boxes activates the delete button in the upper right. This allows you to delete the Historical Hunt(s) that you have checked, along with all matches for the selected Historical Hunt(s). |
| Status | Status column indicates the completion percentage and status of the Hunt:
|
| Historical Hunt Name | Contains the name of the Historical Hunt. |
| Matches | Column indicates the number of matches for this Hunt. This value is computed when the Hunt has finished. |
| Created | Column indicates the date or relative time when the Hunt was started. |
| Actions | Along the right side is the Actions column with several buttons.
|
Deleting a Historical Hunt
To delete a Historical Hunt, click on the “trash can” button in the Action column on the right side of the row. This will delete the Hunt and all of the results in that hunt. You can only delete a Hunt that is not running.
Viewing Historical Hunting Matches
Clicking on the row for a Hunt will display a new table that contains Historical Hunt matches. These Results are paginated, so you can choose the quantity to view and move between pages of matches.
Table of Matches
Each row in the table is a match for the chosen Historical Hunt. The row contains several key pieces of data and some Action buttons.
| Column | What is it for? |
|---|---|
| Checkboxes | Checking one or more of these boxes activates 2 buttons in the upper right.
|
| Rule Name | Column contains the name of the Rule that triggered the match. |
| SHA256 | Column is the SHA256 of the matching artifact. There is a copy icon that will copy the hash to your clipboard. |
| Malware Family Name | Column is the name of Malware Family associated with the artifact that matched the Rule. If the artifact was determined to be Benign, it is possible that the Malware Family name is blank. |
| PolyScore | Column shows the PolyScore for each match. |
| Detections | Column shows the number of malicious assertions / total assertions for the matched artifact. |
| Matched On | Is the date or relative time when the match happened. |
| Actions | Along the right side is the Actions column with several buttons.
|
Filter
In the upper right above the table is the Filter. You can define a Filter to limit the set of matches displayed in the table of matches. The Filter currently supports filtering by:
- Rule Name
- Malware Family Name
- PolyScore
Deleting Historical Hunt Matches
Using the Historical Hunt matches table, you can delete matches one at a time, or in bulk. To delete one at a time, click on the delete icon in the Actions column on the right side of the row. To delete in bulk, check one or more of the checkboxes in the first column and then click on the delete icon in the upper right.