@quantum-sec/kql-test-harness

kql-test-harness

Test harness for running Microsoft Log Analytics queries and verifying outputs.

Prerequisites

• Directory names should be kebab-case
• ./parsers or rules/<DEVICE_TYPE>/<PRODUCT_NAME>/<PRODUCT_VERSION>/
  • if the product doesn't have versions omit that portion of the path
  • if all versions of a product are compatible with one another, omit that portion of the path

Each bottom-level directory should contain:

• The parser (.kql) or rule (.yaml) itself as a file:
  • This file should be the PascalCase name of the function suffixed with _Security
  • This file should contain a Jasmine spec file containing integration tests for the parser.
  • This file should contain a metadata.json file containing targetSchema and schemaVersion.
    • targetSchema should be suffixed with _Security appended with _Schema.
    • schemaVersion should be the git revision of the schema being reference with.
    • Note: To maintain backward compatibility both targetSchema and schemaVersion can be defined in the KQL parser file.

Running Integration Tests

1. Create a service principal in Azure Active Directory using App Registration option.

2. Add API permission Read Log Analytics data as user to service principal. This can be found in Log Analytics API from the list.

3. Give the service principal access in Azure log analytics workspace with Contributor role.

4. Configure your connection to Azure by setting the following environment variables:

   • AAD_TENANT_ID - Azure Active Directory Tenant ID.
   • AAD_CLIENT_ID - Client ID of Service principal created.
   • AAD_CLIENT_SECRET - Client Secret of service principal created.
   • ALA_WORKSPACE_ID - Azure Log Analytics Workspace ID to be used for running KQL queries.

Usage

To install this package in your project, simply use NPM:

npm install --save @quantum-sec/kql-test-harness

Note: You may also need to install peer dependencies.

These will be listed in the output of the npm install command.

Once the package is installed in your project, you can import the classes or types you want to use:

import { ILogAnalyticsQueryContext, KqlTestHarness, KqlTestParserHarness } from '@quantum-sec/kql-test-harness';

Currently this package supports testing for KQL rules and parsers.

Creating a Test Harness for Parsers

  const harness: KqlTestHarness = new KqlTestParserHarness();

or

  const harness: KQLTestHarness = new KQLTestHarness({ source: KqlSource.Parser });

Creating a Test Harness for Rules

  const harness: KqlTestHarness = new KqlTestRuleHarness();

or

  const harness: KQLTestHarness = new KQLTestHarness({ source: KqlSource.Rule });

Initializer

The Test Harness takes an initializer that exposes options for specifying

• schemaPath: The path to the base of the schemas directory. This is a relative path from your spec file.

• source: The KQLSource. Current supported sources are Parser and Rule. source is only available on KQLTestHarness. KqlTestParserHarness and KqlTestRuleHarness will pass their respective source when constructed.

• dataTypeFactoryDelegate: A delegate function to override types assigned to column names that are discovered from sample data.

• defaultTimeOutInterval: Number of milliseconds the test will wait for an asyncronous spec. See jasmine.DEFAULT_TIMEOUT_INTERVAL

Check these example tests files for parsers and rules

You can add supporting functions for a KQL query that are placed in a different KQL file by using utility functions. You can pass utility functions as an argument in harness initialization. Example:

    beforeAll(async () => {
    await harness.init({
      utilityFunctions: [
        'LinuxAuditd_Security_Common',
        'LinuxAuditd_Security_Projection',
      ],
    });
  });

Utilize the harness to construct result objects. Example:

  harness.registerSuite('LinuxAuditdEventTypeData', 'LinuxAuditLog_CL', (context: ILogAnalyticsQueryContext) => {
    let result: any;

    beforeEach(() => {
      result = harness.constructResultObject(context.result)[0];

    });

To add sample data you can either use a .JSON file or generate a sample data in test file. For later below is the example:

Here Signature is the values we want to find a specific rule to pass.

Example query : Antivirus_Security | where (Signature contains @"MeteTool" or Signature contains @"MPreter")

  const baseSampleData = [{
    'TimeGenerated': '2021-07-11T21:41:59.88Z',
    'SourceSystem': 'RestAPI',
  }];

    const signatures = [
    'MeteTool',
    'MPreter',
  ];

  const SampleData = baseSampleData.map((row) => {
        (row as any).Signature = Signature;
        return row;
      });

For negative testing, you can add any value to the array to fail the rule beacuse of absent value in sample data.

You can refer to sample tests in source code parsers & rules directory.

Development

To add additional resources to this module, simply add the code files desired and ensure that they're exported from index.ts in the root of the src directory. If you are using sub-modules, ensure that they're exported from that module's index.ts and then subsequently from the root index.ts.

Once you've added your code, make sure it builds and passes ESLint rules and unit tests:

npm run build
npm run lint
npm run test