npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@quantum-sec/kql-test-harness

v2.1.1

Published

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

Downloads

126

Readme

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