Vestigium.Helpers.Kql 3.4.1

Vestigium.Helpers.Kql

KQL-inspired filter dialect and field catalog. Parse, bind against a pack session, evaluate rows. This package does not enumerate processes, services, or counters. Vestigium.Helpers.Processes references Kql — not the other way around.

Identity

KqlCatalog is the field catalog. KqlLoggingCatalog is the event catalog. Do not mix them.

Consume

<PackageReference Include="Vestigium.Helpers.Kql" Version="1.0.0" />

using Vestigium.Helpers.Kql;

using var session = KqlHelper.Create(KqlPack.Process);
var compiled = KqlHelper.Compile("(PID == 10 || Name LIKE '%edge%') && GPU.Usage GT 20", session);

Hosts that have rows call ProcessHelper.Search(query) — that lives in Processes.

Surface

Packs: Process, Service, Thread, System, Adapter.

Operators: == != <> LIKE IN BETWEEN GT LT GE LE < > plus && \|\| !.

Rules that do not move

• Not a process enumerator. No reference to Vestigium.Helpers.Processes.
• Missing / denied / blank string values are unknown, never "". Top-level unknown is not a hit.
• Never log RHS strings, command lines, or passwords.
• Pipe (\| where) is not supported.
• The library never calls VestigiumLogger.Initialize.

Logging

VestigiumLogger.Initialize(cfg =>
{
    cfg.AppId = "PingIQ";                       // host APPID, not Kql
    cfg.LogDirectory = logDir;
    KqlLoggingCatalog.Register(cfg);
});

Writes are no-ops until the host initializes. JSONL lands at %ProgramData%\Vestigium\Logs\{host-APPID}\.

Named events live in EventCatalog/kql.json.

Related

Row hosts: Vestigium.Helpers.Processes, Vestigium.Helpers.Services.

Long-form documents live in Vestigium.Documentation / Helpers / Kql. Folders, not files — current revision sits inside the folder.

Methods (2.2.0)

<field>.<method>(<value>). The catalog declares the type. The library owns the methods.

publisher.contains("Microsoft")
installed.equals(yes)
installed.isTrue()
size.greaterThan(500)
InstallDate.after(date(-5))
InstallDate.between(date(-30), date(0))

Boolean equals and the closed form accept true false yes no y n t f 1 0, any case.

IS is ==. IS NOT is !=. Operator form is unchanged.

Types

A catalog declares the type, or passes typeof.

KqlField.Create("size", typeof(long));
KqlField.Create("route.destination", typeof(KqlIpAddress));
KqlField.Create("installed", KqlType.Boolean);

KqlIpAddress and KqlMacAddress are library types. Subscribing unlocks their methods. CompareAs still works.

Loose forms

A boolean field alone means true: IsX64.

A field then a value, with no operator, means contains for a string and equals for a number or boolean: publisher Microsoft, installed yes.

Size units: 500mb, 1.5gb, 100kb. Date words: today, yesterday, now, and date(-5).