osqtool

A swiss-army tool for testing, creating, and manipulating osquery query packs.

Installation

With Go v1.20+ installed, run:

go install github.com/chainguard-dev/osqtool/cmd/osqtool@latest

Usage

osqtool supports 4 commands:

• apply - programatically manipulate an osquery query pack, for instance, adjusting intervals
• pack - create a JSON pack file from a directory of raw SQL files
• unpack - extract raw SQL files from a JSON query pack file
• run - run an osquery pack file or directory of SQL queries with human and diff-friendly output
• verify - verify that the queries in a query pack, directory, or raw SQL file are valid and test well

apply

Want to take an osquery pack from the internet, but make changes to it programatically? osqtool has you covered:

curl https://raw.githubusercontent.com/osquery/osquery/master/packs/it-compliance.conf \
  | osqtool --min-interval=8h --platforms linux,posix --exclude os_version apply -

This will set all queries to an 8-hour interval, remove Windows-specific queries, and exclude a query named os_version.

Pack

Create an osquery pack configuration from a recursive directory of SQL files:

osqtool pack /tmp/osx-attacks

Here's the example output:

{
  "queries": {
    "Aobo_Keylogger": {
      "query": "select * from launchd where name like 'com.ab.kl%.plist';",
      "interval": "3600",
      "version": "1.4.5",
      "description": "(http://aobo.cc/aobo-mac-os-x-keylogger.html)",
      "value": "Artifact used by this malware"
    },
    "Backdoor_MAC_Eleanor": {
      "query": "SELECT * FROM launchd WHERE name IN ('com.getdropbox.dropbox.integritycheck.plist','com.getdropbox.dropbox.timegrabber.plist','com.getdropbox.dropbox.usercontent.plist');",
      "interval": "3600",
      "version": "1.4.5",
      "description": "(https://blog.malwarebytes.com/cybercrime/2016/07/new-mac-backdoor-malware-eleanor/)",
      "value": "Artifact used by this malware"
    },
...

The pack command supports the same flags as the apply command. In particular, you may find --exclude, --exclude-tags, and --verify useful.

Run

Run a set of queries!

osqtool run incident-response.conf

Example output:

block_devices (7 rows)
----------------------
block_size:512 label: model: name:/dev/nvme0n1 parent: size:488397168 type: uuid: vendor:
block_size: label: model: name:/dev/nvme0n1p1 parent:/dev/nvme0n1 size:614400 type: uuid: vendor:
block_size: label: model: name:/dev/nvme0n1p2 parent:/dev/nvme0n1 size:415929892 type: uuid: vendor:
block_size: label: model: name:/dev/nvme0n1p3 parent:/dev/nvme0n1 size:71843677 type: uuid: vendor:
block_size:512 label: model:'SD Card Reader' name:/dev/sda parent: size:0 type: uuid: vendor:CalDigit
block_size:512 label: model: name:/dev/dm-0 parent: size:415925796 type: uuid: vendor:
block_size:512 label: model: name:/dev/dm-1 parent: size:71839581 type: uuid: vendor:

crontab (1 rows)
----------------
command:'root run-parts /etc/cron.hourly' day_of_month:* day_of_week:* event: hour:* minute:01 month:* path:/etc/cron.d/0hourly

disk_encryption (0 rows)

Unpack

Extract an osquery pack into a directory of SQL files:

osqtool --output=/tmp/osx-attacks unpack osx-attacks.conf

Here is example output:

Writing 745 bytes to /tmp/out/OceanLotus_dropped_file_1.sql ...
Writing 268 bytes to /tmp/out/OSX_MaMi_DNS_Servers.sql ...
Writing 328 bytes to /tmp/out/OSX_ColdRoot_RAT_Files.sql ...
Writing 209 bytes to /tmp/out/iWorm.sql ...
74 queries saved to /tmp/out

The unpack command supports the same flags as the apply command.

Verify

Verify that the queries are valid in a pack, SQL file, or directory of SQL files

osqtool verify /tmp/detect

Example output:

Verifying "high-disk-bytes-written" ...
high-disk-bytes-written" returned 0 rows within 264.361831ms
Verifying "unexpected-shell-parents" ...
"unexpected-shell-parents" failed validation: /sbin/osqueryi --json [exit status 1]: Error: near line 1: near "sh": syntax error
78 queries found: 55 verified, 10 errored, 13 skipped
"verify" failed: 10 errors occurred:
 * xprotect-reports: /sbin/osqueryi --json [exit status 1]: Error: near line 1: no such table: xprotect_reports

You can set limits on the number of rows returned, amount of runtime per query, per day, or across the pack, see --help for more information.

Common Flags

Here are the options that are available to apply, unpack, pack, and verify

  -default-interval duration
        Interval to use for queries which do not specify one (default 1h0m0s)
  -exclude string
        Comma-separated list of queries to exclude
  -exclude-tags string
        Comma-separated list of tags to exclude (default "disabled")
  -max-interval duration
        Queries can't be scheduled more often than this (default 15s)
  -max-query-daily-duration duration
        Maximum duration for a single query multiplied by how many times it runs daily (checked during --verify) (default 1h0m0s)
  -max-query-duration duration
        Maximum query duration (checked during --verify) (default 4s)
  -max-results int
        Maximum number of results a query may return during verify (default 1000)
  -max-total-daily-duration duration
        Maximum total query-duration per day across all queries (default 6h0m0s)
  -min-interval duration
        Queries cant be scheduled less often than this (default 24h0m0s)
  -multi-line
        output queries is multi-line form. This is accepted by osquery, but technically is invalid JSON.
  -output string
        Location of output
  -platforms string
        Comma-separated list of platforms to include
  -single-quotes
        Render double quotes as single quotes (may corrupt queries)
  -skip_headers
        If true, avoid header prefixes in the log messages
  -tag-intervals string
        modifiers to the default-interval based on query tags (default "transient=5m,postmortem=6h,rapid=15s,often=x/4,seldom=2x")
  -verify
        Verify the output
  -workers int
      Number of workers to use when verifying results (0 for automatic)

At the moment, flags must be declared before the subcommand. ¯\_(ツ)_/¯