osquery-query-helper

Files (4)

• SKILL.md
• standard_osquery_schema.spec · resources/
• detect-format.sh · scripts/
• extract-table.sh · scripts/

SKILL.md (first lines)

# Osquery Query Helper

## What This Skill Does

Help users with all aspects of osquery query work:

- **Write queries** from scratch based on investigation goals
- **Validate queries** the user has written against the schema
- **Troubleshoot queries** that aren't working as expected
- **Suggest improvements** for performance and accuracy

All work is grounded in the tables and columns defined in the provided schema files for the specified EDR platform.

## When to Use

- User needs a query written for incident response or threat hunting
- User wants to validate an existing query against the correct schema
- User has a query that's failing and needs help troubleshooting
- User wants suggestions to improve query performance

---

## Schema File Format

Schema files are located in `resources/` and named by EDR platform: `<platform>_osquery_schema.spec`

- `standard_osquery_schema.spec` — Baseline vanilla osquery (default when no platform specified)
- EDR-specific examples: `bitdefender_`, `kolide_`, `crowdstrike_`, `sentinelone_`, `carbonblack_`

To discover available platforms:
```bash
ls resources/*_osquery_schema.spec 2>/dev/null || ls resources/*.spec
```

### Platform Notation Formats

Schema files use **one of two formats** to indicate OS compatibility:

#### Format 1: Explicit `platforms([...])` field

```
table_name("<table_name>")
description("Brief description.")
schema([
    Column("column_name", TYPE, "Column description")
])
implementation("<table_name>@genTable")
platforms(["darwin", "linux", "windows"])
```

#### Format 2: `#platform` marker before table definitions

A platform marker on its own line applies to all tables until the next marker:

```
#darwin
table_name("<mac_only_table>")
...

#linwin
table_name("<linux_windows_table>")
...
```

### Platform Marker Reference

| Marker | Platforms |
|--------|-----------|
| `#darwin` | macOS only |
| `#linux` | Linux only |
| `#windows` | Windows only |
| `#linwin` | Linux and Windows |
| `#macwin` | macOS and Windows |
| `#posix` | macOS, Linux, FreeBSD |
| `#sleuthkit` | macOS, Linux (requires The Sleuth Kit) |
| `#utility` | Cross-platform utility tables |
| `#cross-platform` | All supported platforms |

---

## Schema Lookup Procedure

The schema files are large. **Always** follow the workflow below to extract table definitions.

Helper scripts are provided in `scripts/` to simplify complex operations:
- `scripts/detect-format.sh` - Determines schema format
- `scripts/extract-table.sh` - Extracts complete table definitions

### 1. Search for Relevant Tables

```bash
# Search by table name keyword
grep -i 'table_name(".*<keyword>' "$SCHEMA_FILE"

# Search descriptions for concepts
grep -i 'description(".*<concept>' "$SCHEMA_FILE"
```

### 2. Extract Full Table Definition

Use the extraction script to get the complete table definition:

```bash
bash scripts/extract-table.sh <schema_file> <table_name>
```

Example:
```bash
bash scripts/extract-table.sh resources/standard_osquery_schema.spec processes
```

The script automatically:
- Detects the schema format (platforms array vs platform markers)
- Extracts the complete table definition including all columns and platform info
- Includes the `#platform` marker for Format 2 schemas

If you need to check the format manually:
```bash
bash scripts/detect-format.sh <schema_file>

From tsale/awesome-dfir-skills, Apache-2.0.

More from tsale/awesome-dfir-skills