kompli

# Copilot Coding Agent Instructions for kompli

> Trust these instructions first. Only search the repo if information here is incomplete or found to be incorrect.

## Project Overview

Kompli is a Linux security compliance engine derived from Azure OSConfig. The repository keeps the ComplianceEngine module and the direct dependencies needed to build, test, package, and fuzz that module.

The code is written in C11/C++11, uses CMake and vcpkg, and targets Linux only.

## Repository Layout

```
src/
  CMakeLists.txt                  Root CMake file and build options
  adapters/mc/complianceengine/   Machine Configuration adapter for ComplianceEngine
  common/
    commonutils/                  Shared OS utility functions used by ComplianceEngine
    logging/                      Circular file logging
    mpiclient/                    MPI REST API client used by the MC adapter
    parson/                       Vendored JSON parser
    telemetry/                    Telemetry support used by ComplianceEngine
  modules/
    complianceengine/             ComplianceEngine module and tests
    inc/                          Module interface headers
    mim/                          ComplianceEngine MIM definition
    schema/                       MIM validation schema
  tests/fuzzer/                   ComplianceEngine libFuzzer target
external/vcpkg/                   vcpkg package manager submodule
devops/                           Remaining build, package, and container assets
```

## Build Instructions

### Prerequisites

- CMake >= 3.21
- GCC or Clang with C11/C++11 support
- Git submodules initialized with `git submodule update --init --recursive`
- `VCPKG_ROOT` unset, so the project uses `external/vcpkg`

### Clean Build

```bash
cmake -S src -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON -DBUILD_TELEMETRY=OFF
cmake --build build --config Release --parallel $(nproc)
```

Build outputs include `build/adapters/mc/complianceengine/libOsConfigResourceComplianceEngine.so` and `build/modules/bin/complianceengine.so`.

### Running Tests

```bash
ctest --test-dir build --output-on-failure -j$(nproc)
```

Tests are registered from the retained common libraries and `src/modules/complianceengine/tests/`. Some tests requiring root or special filesystem permissions are skipped when run as a normal user.

## CI Checks

Pull requests run the retained build, formatting, static-analysis, sanitizer, and CodeQL workflows. Use `-DBUILD_TELEMETRY=OFF` for local builds unless telemetry credentials are intentionally configured.

## Formatting and Linting

Run pre-commit before submitting changes:

```bash
python3 -m pre_commit run --all-files
```

The clang-format and clang-tidy hooks focus on ComplianceEngine and telemetry C++ sources.

## ComplianceEngine Module

ComplianceEngine evaluates security compliance rules using recursive payloads with logical combinators (`allOf`, `anyOf`, `not`), built-in C++ procedures, and Lua scripts. It supports audit and remediation actions.

Rule payloads are generated by the Compliance Augmentation Engine, which transforms benchmark content into JSON payloads and base64-encodes them into MOF fields consumed by the MC adapter.

Key directories:

```
src/modules/complianceengine/
  src/lib/              Core engine, evaluator, procedures, and Lua integration
  src/so/               Module shared-object entry point
  src/benchmarkio/      Benchmark-definition parsing + input-file security
  src/kompli/           kompli CLI tool
  src/lua-evaluator/    Lua evaluator tool
  tests/                Unit tests
```

When adding or changing built-in procedures, keep the procedure implementation, schema, tests, and generated procedure map in sync.