Prior to Osquery 4.2.0, Osquery's FIM capabilities only worked on macOS and
supported version of Linux. To fill this gap, Trail of Bits engineer
@woodruffw created a new virtual table called
ntfs_journal_events to finally bring basic FIM capabilities to osquery on
In this tutorial, we will take a look at how you can use Kolide's SaaS app (K2),
to configure and ingest
- A Kolide K2 account. You can sign up for a free trial at https://k2.kolide.com.
- A Windows 10 device enrolled in K2 with Osquery 4.2.0 or greater.
- Physical or remote access to the Windows 10 device so that you can generate events to monitor.
The FIM in osquery is composed of two distinct pieces:
- A FIM category which defines monitored paths. (eg.
- An events table query which populates results. (eg.
SELECT * FROM ntfs_journal_events;)
Kolide K2 makes it easy to get up and running with the osquery FIM with minimal configuration. Let's setup a basic FIM configuration to monitor the changes of the User's Downloads folder on a Windows device.
To do so we will need to perform three easy steps:
- Enable the osquery Options for Windows events.
- Define a FIM category.
- Write an
To use the FIM we will first need to Enable the NTFS Event Publisher by
going to the Osquery Settings
page and setting the dropdown state to
Next, we will configurea FIM category. A FIM category defines a watched path, or set of paths, which will be flagged as the target of our events query.
FIM categories support the usage of wildcards, to accommodate relative paths that may be different across devices. For example watching directories within a User directory:
C:\Users\fritz\Downloads C:\Users\chris\Downloads C:\Users\kevin\Downloads
All of these directories can be distilled down to a single relative path using the following wildcard approach:
A trailing slash or trailing
%% wildcard should NOT be used when defining
paths or you will not recursively search subdirectories.
The last piece needed before we can start emitting data is a valid osquery SQL query to populate results. We will need this query to run on a recurring schedule which we can configure by including it in an osquery Query Pack.
- Create a new Query Pack by going to Log Pipeline/Osquery Packs
- Click the button Add Pack > New Empty Pack
- Name your pack and select Windows as the Platform
Once we've created our Query Pack, we can add our query to it:
- Within the new pack Click the button labeled Add New Query
- Type a name for your query
- Add the following query:
SELECT * FROM ntfs_journal_events;
- Select Windows for Platform
- Configure an interval (3600 is the default, which is every hour but we suggest choosing a shorter interval like 10s so that you can verify everything is working)
- Choose Diff (additions only) as the log type. (Evented tables in Osquery are different from other tables in that diff removals and snapshot results are not semantically meaningful.)
- Click Save.
Now that you have your new FIM configuration setup, you can test it by
downloading some files to your test Windows device. If you set a frequent
interval for your
ntfs_journal_events query, you should start seeing results
quickly once you perform any actions that trigger the FIM.
Results can be previewed in Kolide's Live Log Viewer. This viewer listens for all logs emitted by the queries in your pack schedule and allows you to preview the output of your configured Query Packs and confirm that osquery is emitting the desired output.
Let's take a look at what we have got so far by renaming and changing the contents of a file:
As we can see we have two actions recorded by osquery a
ntfs_journal_events table can emit one of thirty-two distinct events.
Now that we've generated useful logs, Kolide enables you to forward them to any valid log destinations. For more information on supported Log Destinations and how to configure them, please refer to our help documentation.
There are a couple of items to consider while configuring your FIM ingestion rules.
Since the FIM supports file GLOBs you may be tempted to specify something like
C:\Users\%\Downloads\%% in your FIM category. While this doesn't cause errors,
specifying this way, in-lieu of monitoring the directory itself, may result in
unexpected behavior like the following:
- Osquery agent retrieves FIM configuration
- Recursively searches paths specified by the FIM category (eg.
- Registers each file found via that pattern to be watched for changes.
This means that files created after FIM configuration retrieval (during which, files are registered to be watched) will be ignored by the FIM.
In our testing we have found that you may need restart the Kolide Launcher after enabling the NTFS Event Publisher from the K2 Osquery Options screen. To restart the service, simply open the Services manager, right-click the service named LauncherKolideK2Svc and press Restart.
- Read the
ntfs_journal_eventsPR in the Osquery Github Repo
- Kolide's Log Pipelie Docs
- Osquery's FIM Documentation
Kolide K2, our SaaS osquery solution, is the easiest to use and most advanced osquery fleet manager available today.
Start capturing Windows file events today, with a free trial of Kolide (no payment information or credit card required).