5. Scan
This chapter is a quick introduction on how to run a THOR scan and how to personalize scans to better fit your environment and expectations.
Please note, the command line arguments are used to fine tune your scans and yield potentially better results for your use cases.
There is no "one fits all" command line argument, but we designed THOR to cover the broadest area with minimal impact in the default operating mode. Default in this case means no additional command line arguments.
5.1. Quick Start
Follow these steps to complete your first THOR scan
Make sure you've read the Before You Begin guide
Open a command line as administrative user
Administrator on Windows
root on Linux and macOS
Navigate to the folder in which you've extracted the THOR package and placed the license file(s)
Start THOR on your command line
thor64.exe
on 64-bit Windows systemsthor.exe
on 32-bit Windows systemsthor-linux-64
on x86-64 Linux systemsthor-linux
on i386 Linux systemsthor-macos
on macOS
Wait until the scan has completed (this can take between 20 and 180 minutes)
When the scan is finsihed, check the text log and HTML report in the THOR program directory
5.2. Often Used Parameters
Parameter |
Description |
---|---|
--soft |
Reduce CPU usage, skip all checks that can consume a lot of memory (even if only for a few seconds) |
--quick |
Perform a quick scan (skips Eventlog and checks only the most relevant folders); see Scan Modes |
-e target-folder |
Write all output files to the given folder |
5.3. Parameters possibly relevant for your Use Case
Parameter |
Description |
---|---|
-c, --cpulimit integer |
Instruct THOR to pause all scanning if the systems CPU load is higher than the value specified. Please see CPU Limit (--cpulimit) for more information. |
--allhds |
By default THOR scans only the C: partition on Windows machines and other files/folders only in cases in which some reference points to a different partition (e.g. configured web root of IIS
is on |
--lookback days --globallookback |
Only check the elements changed or created during the last X days in all available modules (reduces the scan duration significantly) |
5.4. Risky Flags
This list contains flags that should better be avoided unless you know exactly what you're doing.
Parameter |
Description |
---|---|
--intense |
long runtime, stability issues due to disabled resource control |
--c2-in-memory |
many false positives on user workstations (especially browser memory) |
--alldrives |
long runtime, stability issues due to scan on network drives or other remote file systems |
--mft |
stability issues due to high memory usage |
--dump-procs |
stability issues, possibly high disk space usage (free disk space checks are implemented but may fail) |
--full-registry |
longer runtime, low positive impact |
5.5. Lesser Known But Useful Flags
This list contains flags that are often used by analysts to tweak the scan in useful ways.
Parameter |
Description |
---|---|
--allreasons |
Show all reasons that led to a certain score |
--printshim |
Print all available SHIM cache entries into the log |
--utc |
Print all timestamps in UTC (helpful when creating timelines) |
--string-context num-chars |
Number of characters preceeding and following the string match to show in the output |
5.6. Help and Debugging
You can use the following parameters help you to understand THOR and the output better.
Parameter |
Description |
---|---|
--debug |
Get debug information if errors occur |
--help |
Get a help with the most important scan options |
--fullhelp |
Get a help with all scan options |
5.7. Examples
5.7.2. Logging to Syslog Server
The following command instructs THOR to log to a remote syslog server only.
thor64.exe --nohtml --nocsv --nolog -s syslog.server.net
5.7.3. Scan Run on a Single Directory
thor64.exe --lab -p C:\ProgramData
thor64.exe --lab -p I:\mounted\_image\disk1
Important
This feature requires a forensic lab license type which is meant to be used in forensic labs.
You can imitate a lab scan without a lab license with these command line flags:
thor64.exe -a Filescan --intense --norescontrol --nosoft --cross-platform -p C:\ProgramData
5.7.4. Save the result files to a different directory
thor64.exe -s 10.1.5.14 -e Z:\
5.7.5. Only scan the last 7 days of the Windows Eventlog and log files on disk
thor64.exe --lookback 7
5.7.6. Scan System with Defaults and Make a Surface Scan
By default, the surface scan (DeepDive) applies all YARA rules in "./custom-signatures" folder. In this example, all output files are written to a network share.
thor64.exe --deepdivecustom -e \\server\share\thor_output\
5.7.7. Intense Scan and DeepDive on a Mounted Image
The following are two examples on how to scan a mounted image on Windows and Linux.
5.7.7.1. Mounted as Drive Z
thor64.exe --lab --deepdive -p Z:\
5.7.7.2. Mounted as /mnt
thor64.exe --lab --deepdive -p /mnt
Important
Lab scanning mode requires a forensic lab license type, which is meant to be used in forensic labs.
5.7.8. Scan Multiple Paths
thor64.exe --lab -p C:\\ D:\\webapps E:\\inetpub
Hint
non-existent directories will be automatically skipped
5.7.9. Scan All Hard Drives (Windows Only)
thor64.exe --allhds
5.7.10. Don't Scan Recursively
To instruct THOR to scan a folder non-recursively use the :NOWALK
suffix.
thor64.exe -a FileScan -p C:\Windows\System32:NOWALK
5.8. Run a Scan with Specific Modules
With the parameter -a
you can run a single module or select a set of
modules that you'd like to run. All available modules can be found in the
section Scan Module Names.
Run a Rootkit check only:
thor64.exe -a Rootkit
Run the Eventlog and file system scan:
thor64.exe –a Eventlog -a Filescan
5.9. Select or filter Signatures during Initialization
THOR 10.7.8 introduces the Init Selector
and Init Filter
functionalities,
allowing users to fine-tune and customize their scanning process for
improved accuracy and efficiency.
You can use these flags to limit the signature set to a certain campaign, threat or threat actor.
The filter values are applied to:
Rule name
Tags
Description
Here are some examples:
thor64.exe --init-selector ProxyShell
You can pass multiple selector keywords separated by comma:
thor64.exe --init-selector RANSOM,Lockbit
Or filter a set of signatures that only cause false positives in your environment:
thor64.exe --init-filter AutoIt
It is important to note that while these features offer flexibility and customization, we recommend utilizing a limited signature set only for specific use cases. This approach is particularly suitable when scanning exclusively for indicators related to a specific campaign. By understanding the proper utilization of Init Selectors and Init Filters, users can optimize their scanning process and effectively identify targeted threats.
The main advantages of a reduced signature set are:
improved scan speed
lower memory usage
5.10. PE-Sieve Integration
THOR integrates PE-Sieve, an open-source tool by @hasherezade to check for malware masquerading as benevolent processes.
PE-Sieve can be activated by using the --processintegrity
flag. It
runs on Windows as part of the ProcessCheck module and is capable of
detecting advanced techniques such as Process Doppelganging.
When investigating infections, you can also raise
the sensitivity of the integrated PE-Sieve beyond the default with
--full-proc-integrity
(at the cost of possible false positives).
THOR reports PE-Sieve results as follows:
Findings |
THOR's Reporting Level |
---|---|
Replaced PE File |
Warning |
Implanted PE File |
Warning |
Unreachable File |
Notice |
Patched |
Notice |
IAT Hooked |
Notice |
Others |
No Output in THOR |
See the PE-Sieve documentation for more details on these values.
5.11. Multi-Threading
Starting from version 10.6, THOR supports scanning a system with multiple threads in parallel, allowing for a significant increase in speed in exchange for a higher CPU usage.
To use this feature, use the --threads
flag which allows you to
specify THOR's number of parallel threads.
When using the --lab
(Lab Scanning), --dropzone
(sample drop
zone) or --thunderstorm
(Thunderstorm) command line flags, THOR will
default to using as many threads as the system has CPU cores; otherwise,
THOR will still default to running with a single thread.
Note
The above listed modes are only available with the "Lab", "Thunderstorm" and "Incident Response" license type.
5.11.1. Enabled Modules
Not all modules support multi-threading. It is currently supported for:
Filescan
RegistryChecks
Eventlog
Thunderstorm (Thunderstorm License needed)
Dropzone (Lab License needed)
5.12. Plugins
Starting with 10.8, THOR supports plugins. They can support a THOR scan in several ways:
Parsing a file format that THOR does not (yet) support
Checking more complex conditions that cannot be written as custom IOCs or rules
Extending THOR output in custom, user-defined ways
...
5.12.1. Writing a Plugin
Plugins are written in Golang. They communicate with THOR via an interface which is defined in https://github.com/NextronSystems/thor-plugin.
Plugins must contain an Init
function which is called when THOR starts; at this time, they can
register hooks. Hooks are invoked during the scan whenever something is scanned that fulfills
the conditions specified for the hook.
When such an element is scanned, the plugin hook is called with that element (e.g., a file), and the plugin can now proceed to parse or check this element. It can call specific functions to:
Log a finding
Log an informational message
Return data back to THOR for further analysis
Examples can be found at https://github.com/NextronSystems/thor-plugin/tree/master/examples.
Warning
When a plugin panics, it can cause the THOR scan to fail. Write your plugins with care.
Note
Plugins only have access to a subset of the standard library. If more features are required, please let us know.
5.12.2. Using a Plugin
Plugins need to be placed in the plugins
folder in the THOR directory.
Each file in this folder with the .go
extension is executed as a separate plugin.
Warning
Plugins contain executable code that is run by THOR. For this reason, never run any plugins that do not come from a trusted source.
5.12.3. Disabling Plugins
To disable all plugins, use --no-plugins
.