https://github.com/chainguard-dev/osqtool
Automated testing, generation & manipulation of #osquery packs
https://github.com/chainguard-dev/osqtool
Last synced: about 2 months ago
JSON representation
Automated testing, generation & manipulation of #osquery packs
- Host: GitHub
- URL: https://github.com/chainguard-dev/osqtool
- Owner: chainguard-dev
- License: apache-2.0
- Created: 2022-10-10T12:00:40.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-16T14:17:50.000Z (7 months ago)
- Last Synced: 2025-04-09T15:05:43.345Z (about 2 months ago)
- Language: Go
- Homepage:
- Size: 1.61 MB
- Stars: 72
- Watchers: 5
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# osqtool
[](https://github.com/chainguard-dev/osqtool/actions)
[](https://goreportcard.com/badge/github.com/chainguard-dev/osqtool)
[](https://github.com/chainguard-dev/osqtool/releases/latest)
[](http://github.com/badges/stability-badges)
A swiss-army tool for testing, creating, and manipulating [osquery](https://osquery.io/) query packs.
## Installation
With [Go](https://go.dev/) v1.20+ installed, run:
```shell
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:
```shell
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:
```shell
osqtool pack /tmp/osx-attacks
```
Here's the example output:
```json
{
"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!
```shell
osqtool run incident-response.conf
```
Example output:
```log
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:
```shell
osqtool --output=/tmp/osx-attacks unpack osx-attacks.conf
```
Here is example output:
```log
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
```shell
osqtool verify /tmp/detect
```
Example output:
```log
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. `¯\_(ツ)_/¯`