asim-parser-filter-validator

# ASIM Parser Filter Validator Validates that an ASIM parser's filtering parameters (e.g. `disabled`, `starttime`, `endtime`, `srcipaddr_has_any_prefix`, etc.) behave correctly by running queries against a Log Analytics workspace. This skill is a **pure PowerShell** implementation that uses `az CLI` for authentication. No Python, Azure SDK packages, or YAML modules are required. - **PowerShell 7+** - **Azure CLI** (logged in via `az login`) ## What it tests For every filtering parameter declared in the parser's KQL function signature: | Parameter type | Tests performed | | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `disabled` | `disabled=true` returns 0 rows; `disabled=false` returns rows | | `datetime` (`starttime` / `endtime`) | Filtering by the midpoint timestamp returns fewer rows than unfiltered | | Scalar (`string`, `int`) | Filtering by a real value returns exactly that value; filtering by a fictitious value returns 0 rows | | `dynamic` (`*_has_any`, `*_has_all`, `*_has_any_prefix`) | Filtering by one/two real values returns fewer rows; fictitious value returns 0 rows; substring / prefix variants tested where applicable | ## Supported schemas AgentEvent, AlertEvent, AssetEntity, AuditEvent, Authentication, DhcpEvent, Dns, FileEvent, NetworkSession, ProcessEvent, RegistryEvent, UserManagement, WebSession. ## Inputs | Input | Required | Description | | --------------- | -------- | ----------------------------------------------------------------- | | Parser KQL path | Yes | Path to the ASIM parser `.kql` file to test | | Schema name | Yes | ASIM schema name (e.g. `Dns`, `Authentication`, `NetworkSession`) | | Workspace ID | Yes | Log Analytics workspace GUID to run queries against | ## How to run ```powershell .\scripts\asimFilterTest.ps1 -ParserFile "{PathToFilterParserKQL}" -SchemaName "{SchemaName}" -WorkspaceId "{your-workspace-guid}" ``` ## Prerequisites 1. **Azure CLI authenticated** — run `az login` if not already logged in. If you get an authentication error, use the `az-cli-command-runner` skill to verify login status. 2. The workspace must contain data for the tables referenced by the parser. ## Interpreting results - **Green** — test passed. - **FAIL** — the filtering parameter did not behave as expected. The failure message indicates which parameter failed and what was expected. - **Known partial validations** — AuditEvent (`EventResult`), Authentication (`EventType`), and Dns (`EventType`) have known single-failure scenarios that are automatically ignored. ### Known acceptable failure reasons (can be ignored) When analyzing filter-validation failures, a failure can be **ignored** if it matches one of these inherent-limitation categories: 1. **Documented schema known exception** — The schema defines a known exception for a parameter (e.g. a multi-value test that cannot succeed because the value combinations do not co-exist in that schema's data). Check whether the ASIM schema documentation lists the parameter as a known exception. 2. **Constant or single-value field by design** — The parser maps the filtered field to a single constant value, so multi-value or reduction-based filtering cannot reduce rows further. This is expected when the source provides only one possible value for that field. 3. **Insufficient distinct values in the test window** — The 2-day query window does not contain enough distinct values for the field to exercise multi-value filtering. This is a data-availability limitation, not a parser bug. When reviewing filter-validation output, analyze each failure message against these categories. If **all other parameters pass** and every failure maps to one of the reasons above, the parser's filtering implementation is considered correct. ## Troubleshooting | Symptom | Fix | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `Failed to acquire access token via az CLI` | Run `az login` | | `No data in the provided workspace` | Ensure the workspace has ingested data for the relevant tables within the last 2 days | | `Schema: X - Not supported` | The schema name is not in the supported list — update the `$AllSchemasParameters` hashtable in `asimFilterTest.ps1` |