### Custom Counting Allocator Example in C

Source: https://context7.com/datadog/libddwaf/llms.txt

Demonstrates how to implement and use a custom counting allocator in C to track memory allocations and deallocations. This example shows the setup for a user-defined allocator and its integration with libddwaf functions.

```c
#include "ddwaf.h"
#include <stdio.h>

// Custom counting allocator for tracking allocations
typedef struct {
    unsigned alloc_count;
    unsigned free_count;
    ddwaf_allocator upstream;
} counting_allocator_data;

void* counting_alloc(void* udata, size_t bytes, size_t alignment) {
    counting_allocator_data* data = (counting_allocator_data*)udata;
    data->alloc_count++;
    return ddwaf_allocator_alloc(data->upstream, bytes, alignment);
}

void counting_free(void* udata, void* p, size_t bytes, size_t alignment) {
    counting_allocator_data* data = (counting_allocator_data*)udata;
    data->free_count++;
    ddwaf_allocator_free(data->upstream, p, bytes, alignment);
}

void allocator_examples(ddwaf_handle handle) {
    // Default allocator - uses standard new/delete
    ddwaf_allocator default_alloc = ddwaf_get_default_allocator();

    // Synchronized pool allocator - thread-safe, good for concurrent contexts
    ddwaf_allocator pool_alloc = ddwaf_synchronized_pool_allocator_init();

    // Unsynchronized pool allocator - faster, single-thread only
    ddwaf_allocator fast_pool = ddwaf_unsynchronized_pool_allocator_init();

    // Monotonic allocator - fastest, memory freed only on destroy
    ddwaf_allocator mono_alloc = ddwaf_monotonic_allocator_init();

    // Custom user allocator with tracking
    counting_allocator_data counter = {0, 0, ddwaf_get_default_allocator()};
    ddwaf_allocator counting_alloc_handle = ddwaf_user_allocator_init(
        counting_alloc, counting_free, &counter, NULL);

    // Create context with pool allocator for output
    ddwaf_context ctx = ddwaf_context_init(handle, pool_alloc);

    // Build input using monotonic allocator (fast allocation, batch free)
    ddwaf_object input;
    ddwaf_object_set_map(&input, 1, mono_alloc);
    ddwaf_object* val = ddwaf_object_insert_key(&input, "test", 4, mono_alloc);
    ddwaf_object_set_string(val, "value", 5, mono_alloc);

    // Evaluate
    ddwaf_object result;
    ddwaf_context_eval(ctx, &input, mono_alloc, &result, 1000000);

    // Cleanup
    ddwaf_object_destroy(&result, pool_alloc);
    ddwaf_context_destroy(ctx);

    printf("Allocations: %u, Frees: %u\n", counter.alloc_count, counter.free_count);

    // Destroy allocators (except default, which is a no-op)
    ddwaf_allocator_destroy(pool_alloc);
    ddwaf_allocator_destroy(fast_pool);
    ddwaf_allocator_destroy(mono_alloc);
    ddwaf_allocator_destroy(counting_alloc_handle);
}

```

--------------------------------

### DDWAF C++ Example

Source: https://github.com/datadog/libddwaf/blob/master/README.md

This snippet demonstrates initializing DDWAF, loading rules, and evaluating data. Ensure DDWAF and yaml-cpp are correctly set up.

```cpp
#include <yaml-cpp/yaml.h>
#include "ddwaf.h"

constexpr std::string_view waf_rule = R"(
version: "2.1"
rules:
  - id: "1"
    name: rule 1
    tags:
      type: flow1
      category: test
    conditions:
      - operator: match_regex
        parameters:
          inputs:
            - address: arg1
          regex: .*
      - operator: match_regex
        parameters:
          inputs:
            - address: arg2
          regex: .*
    on_match: [ block ]
)";

int main()
{
    auto alloc = ddwaf_get_default_allocator();

    YAML::Node doc = YAML::Load(waf_rule.data());

    auto rule = doc.as<ddwaf_object>();

    ddwaf_builder builder = ddwaf_builder_init();
    ddwaf_object diagnostics;
    bool success = ddwaf_builder_add_or_update_config(builder, "config", 6, &rule, &diagnostics);
    ddwaf_object_destroy(&rule, alloc);
    ddwaf_object_destroy(&diagnostics, alloc);

    if (!success) {
        ddwaf_builder_destroy(builder);
        return EXIT_FAILURE;
    }

    ddwaf_handle handle = ddwaf_builder_build_instance(builder);
    ddwaf_builder_destroy(builder);

    if (handle == nullptr) {
        return EXIT_FAILURE;
    }

    ddwaf_context context = ddwaf_context_init(handle, alloc);
    if (context == nullptr) {
        ddwaf_destroy(handle);
        return EXIT_FAILURE;
    }

    ddwaf_object root;
    ddwaf_object_set_map(&root, 2, alloc);

    ddwaf_object *arg1 = ddwaf_object_insert_literal_key(&root, "arg1", 4, alloc);
    ddwaf_object_set_string_literal(arg1, "string 1", 8);

    ddwaf_object *arg2 = ddwaf_object_insert_literal_key(&root, "arg2", 4, alloc);
    ddwaf_object_set_string_literal(arg2, "string 2", 8);

    ddwaf_object ret;
    auto code = ddwaf_context_eval(context, &root, alloc, &ret, 1000000 /* microseconds */);
    std::cout << "Output second run: " << code << '\n';
    if (code == DDWAF_MATCH) {
        YAML::Emitter out(std::cout);
        out.SetIndent(2);
        out.SetMapFormat(YAML::Block);
        out.SetSeqFormat(YAML::Block);
        out << object_to_yaml(ret);
    }

    ddwaf_object_destroy(&ret, alloc);

    ddwaf_context_destroy(context);
    ddwaf_destroy(handle);

    return EXIT_SUCCESS;
}

```

--------------------------------

### Build Example Sources with CMake

Source: https://github.com/datadog/libddwaf/blob/master/examples/CMakeLists.txt

This CMake script iterates through all .cpp files in the LIBDDWAF_EXAMPLE_SOURCE directory, compiles each as a separate executable, and links them against libddwaf_objects, lib_yamlcpp, and lib_rapidjson. It also sets up private include directories.

```cmake
file(GLOB LIBDDWAF_EXAMPLE_SOURCE *.cpp)

foreach(EXAMPLE ${LIBDDWAF_EXAMPLE_SOURCE})
    get_filename_component(EXAMPLE_NAME ${EXAMPLE} NAME_WLE)

    add_executable(${EXAMPLE_NAME} ${EXAMPLE})
    target_link_libraries(${EXAMPLE_NAME} PRIVATE libddwaf_objects lib_yamlcpp lib_rapidjson)
    target_include_directories(${EXAMPLE_NAME} PRIVATE ${LIBDDWAF_PRIVATE_INCLUDES})
endforeach()
```

--------------------------------

### Build and Run Fuzzer Manually

Source: https://github.com/datadog/libddwaf/blob/master/fuzzer/global/README.md

This method requires LLVM to be installed. First, build the fuzzer executable, then run the fuzzing session.

```bash
./fuzzing/build.sh  # build fuzzing/fuzzer executable
./fuzzing/run.sh   # starts a fuzzing session
```

--------------------------------

### Rule with Min/Max Version Constraints

Source: https://github.com/datadog/libddwaf/blob/master/docs/changelog/CHANGELOG-v1.x.md

This example demonstrates how to use `min_version` and `max_version` to control the compatibility of a rule with specific libddwaf versions. Ensure the rule's version requirements align with the libddwaf version being used.

```yaml
  - id: rsp-930-004
    name: SHi Exploit detection
    tags:
      type: shi
      category: exploit_detection
      module: rasp
    min_version: 1.19.0
    max_version  1.19.999
    conditions:
      - parameters:
          resource:
            - address: server.sys.shell.cmd
          params:
            - address: server.request.query
        operator: shi_detector
```

--------------------------------

### Migrate ddwaf_run usage from ddwaf_result to ddwaf_object

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

Example demonstrating the migration from using ddwaf_result to ddwaf_object for handling results from ddwaf_run. It shows how to access events.

```c++
ddwaf_result ret;
auto code = ddwaf_run(context, &root, nullptr, &ret, LONG_TIME);
if (code == DDWAF_MATCH) {
    cout << object_to_yaml(&ret.events);
}
ddwaf_result_free(&ret);
```

```c++
ddwaf_object ret;
auto code = ddwaf_run(context, &root, nullptr, &ret, LONG_TIME);
if (code == DDWAF_MATCH) {
    const ddwaf_object *events = ddwaf_object_find(&ret, "events", sizeof("events") - 1);
    cout << object_to_yaml(events);
}
ddwaf_object_free(&ret);
```

--------------------------------

### Build libddwaf with Specific Targets and Test Suite

Source: https://github.com/datadog/libddwaf/blob/master/README.md

Builds libddwaf with specific configurations (RelWithDebInfo, custom install prefix) and targets, including shared and static libraries, and the test suite. It then navigates to the tests directory and runs the WAF test executable.

```bash
cmake -E make_directory build packages
cd build
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=.. -DCPACK_PACKAGE_DIRECTORY=../packages ..
cmake --build . --config RelWithDebInfo --verbose --target libddwaf_shared --target libddwaf_static  --target waf_test -j
cd ../tests
../build/tests/waf_test
```

--------------------------------

### Iterating Old Actions Array

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

Example of how to iterate through the actions array in the older DD WAF result structure.

```c
ddwaf_result res;
for (unsigned i = 0; i < res.actions.size; ++i) {
    printf("%s", res.actions.array[i]);
}
```

--------------------------------

### Get All Loaded Configuration Paths in libddwaf

Source: https://github.com/datadog/libddwaf/blob/master/docs/changelog/CHANGELOG-v1.x.md

Use this function to retrieve all currently loaded configuration paths from the WAF builder. Ensure the builder is initialized and configurations are added before calling.

```c
ddwaf_builder builder = ddwaf_builder_init(nullptr);
ddwaf_builder_add_or_update_config(builder, LSTRARG("ASM_DD/default"), &default_config, nullptr);
ddwaf_object_free(&default_config);

ddwaf_object paths;
uint32_t count = ddwaf_builder_get_config_paths(builder, &paths, nullptr, 0);

// count: 1
// paths: [ "ASM_DD/default" ]
```

--------------------------------

### Create and Match with Aho-Corasick Lua Module

Source: https://github.com/datadog/libddwaf/blob/master/src/vendor/lua-aho-corasick/README.md

Example of how to create an Aho-Corasick instance with a dictionary and perform a match against a given string using the Lua module.

```lua
local ac = require "ahocorasick"
local dict = {"string1", "string", "etc"}
local acinst = ac.create(dict)
local r = ac.match(acinst, "mystring")
```

--------------------------------

### Legacy Linux Build Package Naming Convention

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

Provides examples of legacy Linux build package names for comparison with the new standardized format. These packages do not include the architecture or environment details in the same way.

```text
libddwaf-1.13.0-linux-x86_64.tar.gz
libddwaf-1.13.0-linux-aarch64.tar.gz
```

--------------------------------

### Traversing Diagnostics Object for Root Span

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

This example demonstrates a mechanism to traverse the new diagnostics object to report rule metrics and errors to the root span, ensuring backward compatibility.

```cpp
ddwaf_object diagnostics;
ddwaf_handle handle = ddwaf_init(&rule, nullptr, &diagnostics);
ddwaf_object_free(&rule);
ddwaf_destroy(handle);

const auto *rules = find_object(&diagnostics, "rules");
if (rules != nullptr) {
    size_t index = 0;
    const ddwaf_object *node = nullptr;
    while ((node = ddwaf_object_get_index(rules, index++)) != nullptr) {
        std::string_view node_key = ddwaf_object_get_key(node, nullptr);

        if (node_key == "loaded") {
            root_span.metrics["_dd.appsec.event_rules.loaded"] = ddwaf_object_size(node);
        } else if (node_key =="failed") {
            root_span.metrics["_dd.appsec.event_rules.error_count"] = ddwaf_object_size(node);
        }  else if (node_key == "errors") {
            root_span.meta["_dd.appsec.event_rules.errors"] = object_to_yaml(*node);
        } else if (node_key == "ruleset_version") {
            root_span.meta["_dd.appsec.event_rules.version"] = ddwaf_object_get_string(node, nullptr);
        }
    }
}
ddwaf_object_free(&diagnostics);
```

--------------------------------

### Generate Stack Action with Stack ID

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

This example shows the structure for the `generate_stack` action type when triggered. It includes the `stack_id` parameter, which is essential for associating the generated stack trace with the correct event.

```json
{
  "generate_stack": {
    "stack_id": "b4c7aff3-8fb0-4f6a-1bc7-582700c46abe"
  }
}
```

--------------------------------

### DDWAF Rule Example and Result

Source: https://github.com/datadog/libddwaf/blob/master/README.md

This YAML demonstrates a sample DDWAF rule designed to detect script tags and its corresponding output when applied to a specific input value. It shows how rule conditions and matches are represented.

```yaml
version: 2.1
rules:
 - id: crs-042-001
   name: Detect a script tag
   tags:
     category: attack_attempt
     type: xss
   conditions:
    - operator: match_regex
      parameters:
        regex: "^<script>"
        inputs:
         - address: http.server.query
```

```yaml
- rule:
    id: crs-042-001
    name: Detect a script tag
    tags:
      category: attack_attempt
      type: xss
  rule_matches:
    - operator: match_regex
      operator_value: ^<script>
      parameters:
        - address: http.server.query
          key_path:
            - q
          value: <script>alert() hello world
          highlight:
            - <script>
```

--------------------------------

### Configure SSRF Operator with Options and Policy

Source: https://github.com/datadog/libddwaf/blob/master/docs/changelog/CHANGELOG-v1.x.md

Example YAML configuration for the SSRF detector operator. Customize heuristic options and policy settings like allowed schemes and forbidden domains.

```yaml
id: rasp-934-100
name: Server-side request forgery exploit
tags:
  type: ssrf
  module: rasp
conditions:
  - parameters:
      resource:
        - address: server.io.net.url
      params:
        - address: server.request.query
        # Additional parameters...
      options:
        authority-inspection: true
        path-inspection: false
        query-inspection: false
        forbid-full-url-injection: true
        enforce-policy-without-injection: false
      policy:
        allowed-schemes: []
        forbidden-domains: []
        forbidden-ips: []
    operator: ssrf_detector
```

--------------------------------

### Filter and List Remote WAF Configurations

Source: https://context7.com/datadog/libddwaf/llms.txt

Retrieves and prints a list of remote configuration paths that match a given regex filter. This is useful for managing specific types of configurations, like those starting with 'ASM/'.

```c
// Filter configurations by regex
void waf_manager_list_remote_configs(waf_manager* mgr) {
    ddwaf_object paths;
    const char* filter = "^ASM/";  // Match paths starting with "ASM/"
    uint32_t count = ddwaf_builder_get_config_paths(
        mgr->builder, &paths, filter, strlen(filter));

    printf("Remote configurations (%u):\n", count);
    ddwaf_object_destroy(&paths, ddwaf_get_default_allocator());
}

```

--------------------------------

### Initialize WAF Builder and Add Configuration

Source: https://context7.com/datadog/libddwaf/llms.txt

Demonstrates initializing the WAF builder, defining rules in JSON format, parsing them into a ddwaf_object, adding the configuration to the builder with a unique path, and finally building the WAF instance. This is the recommended approach for creating WAF instances, especially for dynamic configuration updates.

```c
#include "ddwaf.h"

int main() {
    // Initialize builder
    ddwaf_builder builder = ddwaf_builder_init();
    if (builder == NULL) {
        return EXIT_FAILURE;
    }

    // Define WAF rules in YAML format
    const char* ruleset_json = "{"
        "\"version\": \"2.1\",\n"
        "\"rules\": [{"
            "\"id\": \"xss-001\",\n"
            "\"name\": \"XSS Attack Detection\",\n"
            "\"tags\": {\"type\": \"xss\", \"category\": \"attack_attempt\"},\n"
            "\"conditions\": [{"
                "\"operator\": \"match_regex\",\n"
                "\"parameters\": {"
                    "\"inputs\": [{\"address\": \"http.server.query\"}]",
                    "\"regex\": \"<script[^>]*>\""
                "}
            "}],\n"
            "\"on_match\": [\"block\"]"
        "}]"
    "}";

    // Parse JSON into ddwaf_object
    ddwaf_allocator alloc = ddwaf_get_default_allocator();
    ddwaf_object config;
    if (!ddwaf_object_from_json(&config, ruleset_json, strlen(ruleset_json), alloc)) {
        ddwaf_builder_destroy(builder);
        return EXIT_FAILURE;
    }

    // Add configuration to builder with unique path
    ddwaf_object diagnostics;
    bool success = ddwaf_builder_add_or_update_config(
        builder, "ASM_DD/default", 14, &config, &diagnostics);

    ddwaf_object_destroy(&config, alloc);
    ddwaf_object_destroy(&diagnostics, alloc);

    if (!success) {
        ddwaf_builder_destroy(builder);
        return EXIT_FAILURE;
    }

    // Build WAF instance
    ddwaf_handle handle = ddwaf_builder_build_instance(builder);

    // Builder can be reused for updates or destroyed
    ddwaf_builder_destroy(builder);

    if (handle == NULL) {
        return EXIT_FAILURE;
    }

    // Use handle for request processing...
    ddwaf_destroy(handle);
    return EXIT_SUCCESS;
}

```

--------------------------------

### WAF Instantiation: v1.x ddwaf_init

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-latest.md

Illustrates the WAF instantiation process in libddwaf v1.x using ddwaf_init, including configuration and diagnostics objects.

```c
ddwaf_object ruleset = ...;
ddwaf_config config = ...;

ddwaf_object diagnostics;
ddwaf_handle handle = ddwaf_init(&ruleset, &config, &diagnostics);
```

--------------------------------

### Getting DDWAF Version (Deprecated)

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

The deprecated method for getting the DDWAF version involved a structure and manual printing.

```c
ddwaf_version version;
ddwaf_get_version(&version);
printf("ddwaf version: %d.%d.%d\n", version.major, version.minor, version.patch);

```

--------------------------------

### Deprecated ddwaf_ruleset_info Errors Example

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

An example JSON representation of the `errors` field within the deprecated `ddwaf_ruleset_info` structure, showing parsing errors mapped to rule IDs.

```json
"errors": {
  "missing key 'type'": [
    "blk-001-002"
  ]
}

```

--------------------------------

### Block Request Action Definition Example

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

This example demonstrates the definition of a `block_request` action. It specifies a custom `status_code` of '404' and `type` 'auto'. The `grpc_status_code` is omitted, so its default value of '10' will be used.

```json
{
  "id": "block",
  "parameters": {
    "status_code": "404",
    "type": "auto"
  },
  "type": "block_request"
}
```

--------------------------------

### Build with LTO and PGO

Source: https://github.com/datadog/libddwaf/blob/master/benchmark/scripts/README.md

Use this script to build the waf_benchmark binary with Link-Time Optimization (LTO) and Profile-Guided Optimization (PGO). This process includes an initial build, profile generation, and a final optimized rebuild.

```shell
./benchmark/scripts/build_with_pgo.sh
```

--------------------------------

### Successful Parsing Diagnostics Example

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

An example of a diagnostics object representing a ruleset where all entries were parsed successfully. It shows 'loaded' and 'failed' arrays (empty in this case) and an empty 'errors' map for 'custom_rules' and 'rules_override'.

```json
{
  "custom_rules": {
    "loaded": [
      "a45b55fc-5b57-4002-90bf-58cdf296124c"
    ],
    "failed": [],
    "errors": {}
  },
  "rules_override": {
    "loaded": [
      "index:0",
      "index:1"
    ],
    "failed": [],
    "errors": {}
  }
}

```

--------------------------------

### Build with LTO, PGO, and BOLT

Source: https://github.com/datadog/libddwaf/blob/master/benchmark/scripts/README.md

Execute this script to build the waf_benchmark binary with LTO, PGO, and BOLT optimizations. This method involves two profile-generation stages and results in an optimized binary.

```shell
./benchmark/scripts/build_with_pgo_and_bolt.sh
```

--------------------------------

### New Diagnostics Object Structure Example

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

An example of the expected contents of the `ddwaf_object` used for diagnostics when a WAF is provided with a complete ruleset. It includes maps for various high-level features and metadata like the ruleset version.

```json
{
  "custom_rules": {...},
  "exclusions": {...},
  "rules": {...},
  "rules_data": {...},
  "rules_override": {...},
  "ruleset_version": "1.7.0"
}

```

--------------------------------

### Prepare Configuration Object and Path

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

Before adding or updating a configuration, prepare it as a `ddwaf_object` of type `map` and define a unique string path for its identifier. Ensure the configuration map contains expected top-level keys like `rules`, `exclusions`, etc.

```c
// Generate the configuration as a map containing any of the expected top-level keys, such as `rules, exclusions, etc.
ddwaf_object configuration;
ddwaf_object_map(&configuration);
...

// Use a unique path for this configuration
const char *path = "path/to/configuration/rules-c555e7ee647a3d72c2cb60a32767d586";
uint32_t path_len = (uint32_t)strlen(path);
```

--------------------------------

### Add yaml-cpp External Project

Source: https://github.com/datadog/libddwaf/blob/master/third_party/CMakeLists.txt

Configures yaml-cpp as an external project using ExternalProject_Add. It specifies the URL, installation directory, and various CMake arguments for building and installing the library, including compiler flags and build type.

```cmake
ExternalProject_Add(proj_yamlcpp
    URL https://github.com/jbeder/yaml-cpp/archive/refs/tags/yaml-cpp-0.7.0.zip
    INSTALL_DIR       ${INSTALL_DIR}
    CMAKE_ARGS  -DCMAKE_INSTALL_PREFIX:PATH=<INSTALL_DIR>
                -DCMAKE_INSTALL_LIBDIR=lib
                -DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
                -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
                -DCMAKE_CXX_FLAGS=${CMAKE_CXX_FLAGS}
                -DCMAKE_CXX_FLAGS_RELEASE=${CMAKE_CXX_FLAGS_RELEASE}
                -DCMAKE_CXX_FLAGS_RELWITHDEBINFO=${CMAKE_CXX_FLAGS_RELWITHDEBINFO}
                -DCMAKE_CXX_FLAGS_DEBUG=${CMAKE_CXX_FLAGS_DEBUG}
                -DYAML_CPP_BUILD_TESTS=OFF
                -DYAML_CPP_BUILD_CONTRIB=OFF
                -DYAML_CPP_BUILD_TOOLS=OFF
                -DYAML_CPP_INSTALL=ON
                -DYAML_BUILD_SHARED_LIBS=OFF
                -DYAML_MSVC_SHARED_RT=OFF
                -DCMAKE_POLICY_VERSION_MINIMUM=3.5
                -DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}
                -DCMAKE_OSX_ARCHITECTURES=${CMAKE_OSX_ARCHITECTURES}
                BUILD_BYPRODUCTS ${INSTALL_DIR}/lib/${LIBYAML_FILENAME})
add_library(lib_yamlcpp STATIC IMPORTED GLOBAL)
set_target_properties(lib_yamlcpp PROPERTIES  IMPORTED_LOCATION ${INSTALL_DIR}/lib/${LIBYAML_FILENAME})
target_include_directories(lib_yamlcpp INTERFACE ${INSTALL_DIR}/include)
add_dependencies(lib_yamlcpp proj_yamlcpp)
set_target_properties(lib_yamlcpp proj_yamlcpp PROPERTIES EXCLUDE_FROM_ALL TRUE)
```

--------------------------------

### Initialize and Configure DDWAF Builder

Source: https://github.com/datadog/libddwaf/blob/master/docs/c-api/binding-integration-guide.md

Initializes a DDWAF builder, adds configurations with unique paths, and builds a DDWAF handle. Remember to destroy the builder when no longer needed.

```c
// 1. Initialize builder
ddwaf_builder builder = ddwaf_builder_init();

// 2. Add configurations with unique paths
ddwaf_object diagnostics;
ddwaf_builder_add_or_update_config(builder, "base", 4, base_config, &diagnostics);
ddwaf_object_destroy(&diagnostics, ddwaf_get_default_allocator());
```

--------------------------------

### Example of a Passed Test

Source: https://github.com/datadog/libddwaf/blob/master/validator/README.md

Output indicating that a test has passed as expected. This is a successful validation result.

```text
tests/rule7_004.yaml => Passed

```

--------------------------------

### Initialize WAF Builder with Configuration

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

Instantiate a new WAF builder using a `ddwaf_config` structure to define evaluation limits, obfuscator regexes, and a free function. If `NULL` is provided for config, default values are used.

```cpp
ddwaf_config config{/* limits, obfuscator regexes and free function */};

// Instantiate a new builder using the previously defined ddwaf_config
ddwaf_builder builder = ddwaf_builder_init(config);
```

--------------------------------

### Get Object Type

Source: https://github.com/datadog/libddwaf/blob/master/docs/c-api/api.md

Retrieves the data type of a ddwaf_object. Returns DDWAF_OBJ_INVALID if the input object is NULL.

```c
DDWAF_OBJ_TYPE ddwaf_object_get_type(const ddwaf_object * object)
```

--------------------------------

### Rule with Global Transformers

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

An example of a WAF rule defining a 'lowercase' transformer applied globally to all inputs.

```json
{
  "id": "crs-933-111",
  "name": "PHP Injection Attack: PHP Script File Upload Found",
  "tags": {...},
  "conditions": [...],
  "transformers": [
    "lowercase"
  ]
},
```

--------------------------------

### WAF Instantiation: v2.x ddwaf_init

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-latest.md

Shows the updated WAF instantiation process in libddwaf v2.x using ddwaf_init, where ddwaf_config is removed and allocators are implicitly handled.

```c
ddwaf_object ruleset = ...;

ddwaf_object diagnostics;
ddwaf_handle handle = ddwaf_init(&ruleset, &diagnostics);
```

--------------------------------

### Getting DDWAF Version (1.5.0+)

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

In newer versions, ddwaf_get_version returns a const string directly, simplifying version retrieval.

```c
printf("ddwaf version: %s\n", ddwaf_get_version());

```

--------------------------------

### Build and Run Fuzzer with Docker

Source: https://github.com/datadog/libddwaf/blob/master/fuzzer/global/README.md

Use this command to build the Docker image for fuzzing and then run the fuzzer. This is the simpler method requiring only Docker.

```bash
docker build -f fuzzing/Dockerfile -t fuzzer .
docker run -v $(pwd)/fuzzing:/libddwaf/fuzzing fuzzer ./fuzzing/run.sh
```

--------------------------------

### Get String Object Length

Source: https://github.com/datadog/libddwaf/blob/master/docs/c-api/api.md

Returns the length of the string contained within a ddwaf_object. Returns 0 if the object is not a string.

```c
size_t ddwaf_object_get_length(const ddwaf_object * object)
```

--------------------------------

### Initialize and Update WAF Handle

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

Demonstrates the typical usage of `ddwaf_init` followed by `ddwaf_update` to create a new WAF handle from an existing one. Ensure to free the old handle if the update is successful.

```c
    ddwaf_handle old_handle = ddwaf_init(&ruleset, &config, &info);
    ddwaf_object_free(&ruleset);

    ddwaf_handle new_handle = ddwaf_update(old_handle, &update, &new_info);
    ddwaf_object_free(&update);
    if (new_handle != NULL) {
        ddwaf_destroy(old_handle);
    }
```

--------------------------------

### Counting allocator user data free function

Source: https://github.com/datadog/libddwaf/blob/master/docs/allocators.md

An optional free function for user data. This example is a no-operation function.

```c++
void counting_allocator_udata_free(void *udata)
{
  // noop
}
```

--------------------------------

### Build WAF Instance from Builder

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

Create a WAF instance from the builder. Always check the returned handle for `NULL` to ensure successful instantiation.

```cpp
// Build a new WAF instance, handle any potential failure by checking for NULL
ddwaf_handle handle = ddwaf_builder_build_instance(&builder);
if (handle == NULL) { /* handle failure */ }
```

--------------------------------

### Get Container Object Size

Source: https://github.com/datadog/libddwaf/blob/master/docs/c-api/api.md

Returns the number of elements in a container object (array or map). Returns 0 if the object is not a container.

```c
size_t ddwaf_object_get_size(const ddwaf_object * object)
```

--------------------------------

### Initialize and Update WAF Configuration

Source: https://context7.com/datadog/libddwaf/llms.txt

Initializes the WAF manager with a base configuration and demonstrates adding or updating configurations dynamically. Use this for setting up the WAF with initial rules and applying remote updates.

```c
#include "ddwaf.h"
#include <stdio.h>

typedef struct {
    ddwaf_builder builder;
    ddwaf_handle current_handle;
} waf_manager;

void waf_manager_init(waf_manager* mgr, const ddwaf_object* base_config) {
    mgr->builder = ddwaf_builder_init();
    mgr->current_handle = NULL;

    ddwaf_object diagnostics;
    ddwaf_builder_add_or_update_config(
        mgr->builder, "ASM_DD/default", 14, base_config, &diagnostics);
    ddwaf_object_destroy(&diagnostics, ddwaf_get_default_allocator());

    mgr->current_handle = ddwaf_builder_build_instance(mgr->builder);
}

// Apply remote configuration update
int waf_manager_apply_remote_config(
    waf_manager* mgr,
    const char* config_path,
    const ddwaf_object* config)
{
    ddwaf_object diagnostics;
    bool success = ddwaf_builder_add_or_update_config(
        mgr->builder, config_path, strlen(config_path), config, &diagnostics);

    if (!success) {
        // Log diagnostics errors
        const ddwaf_object* errors = ddwaf_object_find(&diagnostics, "errors", 6);
        if (errors) {
            printf("Config errors found\n");
        }
        ddwaf_object_destroy(&diagnostics, ddwaf_get_default_allocator());
        return -1;
    }

    ddwaf_object_destroy(&diagnostics, ddwaf_get_default_allocator());

    // Build new instance
    ddwaf_handle new_handle = ddwaf_builder_build_instance(mgr->builder);
    if (new_handle == NULL) {
        return -1;
    }

    // Atomically swap handles (in real code, use proper synchronization)
    ddwaf_handle old_handle = mgr->current_handle;
    mgr->current_handle = new_handle;

    // Destroy old handle (safe after all contexts using it are destroyed)
    if (old_handle) {
        ddwaf_destroy(old_handle);
    }

    return 0;
}

```

--------------------------------

### Get String Content

Source: https://github.com/datadog/libddwaf/blob/master/docs/c-api/api.md

Retrieves the C-style string from a ddwaf_object. Optionally returns the string's length. Returns NULL if the object is not a string.

```c
const char * ddwaf_object_get_string(const ddwaf_object * object, size_t * length)
```

--------------------------------

### Builder Initialization: v1.x ddwaf_builder_init

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-latest.md

Demonstrates the initialization of the ddwaf builder in libddwaf v1.x, which required a ddwaf_config object.

```c
ddwaf_config config = ...;
ddwaf_builder builder = ddwaf_builder_init(&config);
```

--------------------------------

### Builder Initialization: v2.x ddwaf_builder_init

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-latest.md

Shows the simplified initialization of the ddwaf builder in libddwaf v2.x, where ddwaf_config is no longer needed.

```c
ddwaf_builder builder = ddwaf_builder_init();
```

--------------------------------

### Block Request Action with Block ID

Source: https://github.com/datadog/libddwaf/blob/master/docs/changelog/CHANGELOG-v1.x.md

Example of a block request action including the new `block_id` parameter for correlation. This is used in v1.29.0.

```yaml
actions:
  block_request:
    status_code: 403
    grpc_status_code: 10
    type: auto
    block_id: "55af6314-9e02-11f0-b0a3-23dee2d4f390"
```

--------------------------------

### Example of a Failed Test (Expected)

Source: https://github.com/datadog/libddwaf/blob/master/validator/README.md

Output indicating that a test failed, as was expected. This is not considered a test failure and will result in a zero exit code.

```text
tests/rule4_015.yaml => Failed (expected): run_test(80): match != ok

```

--------------------------------

### Initialize WAF Builder

Source: https://github.com/datadog/libddwaf/blob/master/docs/c-api/api.md

Creates and initializes a new WAF builder instance. This builder is used to incrementally configure and construct a WAF instance. Default configurations are used if no explicit configuration is provided.

```c
ddwaf_builder ddwaf_builder_init()
```

--------------------------------

### Example of a Failed Test (Unexpected)

Source: https://github.com/datadog/libddwaf/blob/master/validator/README.md

Output indicating that a test failed when it was not expected to fail. This includes the assertion that failed and the WAF output for debugging.

```text
tests/rule8_001.yaml => Failed: run_test(80): match != ok
- rule:
    id: 7
    name: rule7-common-flow
    tags:
      type: flow7_8
      category: category
  rule_matches:
    - operator: match_regex
      operator_value: rule7
      parameters:
        - address: rule7-input
          key_path:
            []
          value: rule7
          highlight:
            - rule7

```

--------------------------------

### List Loaded WAF Configurations

Source: https://context7.com/datadog/libddwaf/llms.txt

Retrieves and prints a list of all configuration paths currently loaded in the WAF builder. This helps in understanding the WAF's current state.

```c
// List loaded configurations
void waf_manager_list_configs(waf_manager* mgr) {
    ddwaf_object paths;
    uint32_t count = ddwaf_builder_get_config_paths(mgr->builder, &paths, NULL, 0);

    printf("Loaded configurations (%u):\n", count);
    for (size_t i = 0; i < ddwaf_object_get_size(&paths); i++) {
        const ddwaf_object* path = ddwaf_object_at_value(&paths, i);
        size_t len;
        const char* str = ddwaf_object_get_string(path, &len);
        printf("  - %.*s\n", (int)len, str);
    }

    ddwaf_object_destroy(&paths, ddwaf_get_default_allocator());
}

```

--------------------------------

### Create Map (v1.x)

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-latest.md

In v1.x, create a map using ddwaf_object_map and add key-value pairs using ddwaf_object_map_addl. Remember to free the map.

```c
ddwaf_object map;
ddwaf_object_map(&map);

// Create value object, then add to map
ddwaf_object value;
ddwaf_object_string(&value, "username");
ddwaf_object_map_addl(&map, "user", 4, &value);

// Create another value and add
ddwaf_object value2;
ddwaf_object_unsigned(&value2, 12345);
ddwaf_object_map_addl(&map, "user_id", 7, &value2);

ddwaf_object_free(&map);
```

--------------------------------

### Add Test and Development Subdirectories

Source: https://github.com/datadog/libddwaf/blob/master/CMakeLists.txt

If testing is enabled, this section adds subdirectories for tests, validator, benchmark, fuzzer, tools, and examples to the build.

```cmake
if (LIBDDWAF_TESTING)
    add_subdirectory(tests EXCLUDE_FROM_ALL)
    add_subdirectory(validator EXCLUDE_FROM_ALL)
    add_subdirectory(benchmark EXCLUDE_FROM_ALL)
    add_subdirectory(fuzzer EXCLUDE_FROM_ALL)
    add_subdirectory(tools EXCLUDE_FROM_ALL)
    add_subdirectory(examples EXCLUDE_FROM_ALL)

    include(cmake/clang-tidy.cmake)
    include(cmake/clang-format.cmake)
endif()
```

--------------------------------

### Get Known Actions

Source: https://github.com/datadog/libddwaf/blob/master/docs/c-api/api.md

Retrieves an array of all possible action types that can be triggered by the current ruleset. The returned array is invalidated by ddwaf_destroy. This function is not thread-safe.

```c
const char *const * ddwaf_known_actions(const ddwaf_handle handle, uint32_t * size)
```

--------------------------------

### Initialize WAF Context with Output Allocator in v2.x

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-latest.md

In v2.x, ddwaf_context_init requires an output allocator for memory management of results and diagnostics.

```c
ddwaf_handle handle = ...;

// Get allocator for output objects (result, diagnostics, etc.)
ddwaf_allocator output_alloc = ddwaf_get_default_allocator();

// Create context with output allocator
ddwaf_context context = ddwaf_context_init(handle, output_alloc);
```

--------------------------------

### Get default allocator

Source: https://github.com/datadog/libddwaf/blob/master/docs/changelog/CHANGELOG-latest.md

Retrieve the default allocator for simple memory management needs using `ddwaf_get_default_allocator()`. This is useful when custom memory management is not required.

```c
ddwaf_get_default_allocator()
```

--------------------------------

### Build libddwaf (Linux/Darwin)

Source: https://github.com/datadog/libddwaf/blob/master/README.md

Builds a static and dynamic library for libddwaf using CMake on Linux and Darwin systems. Ensure you are in the project root directory.

```bash
mkdir -p build && cd build
cmake ..
make -j4
```

--------------------------------

### Define URI Parsing Preprocessor

Source: https://github.com/datadog/libddwaf/blob/master/docs/changelog/CHANGELOG-v1.x.md

Example definition of the `uri_parse` preprocessor. This preprocessor converts a raw URI into a structured map for easier rule targeting.

```yaml
id: decompose-uri
generator: uri_parse
conditions: []
parameters:
  mappings:
    - inputs:
        - address: server.request.uri.raw
      output: server.request.uri
evaluate: true
output: false
```

--------------------------------

### Build DDWAF Benchmark Executable

Source: https://github.com/datadog/libddwaf/blob/master/benchmark/CMakeLists.txt

Configures the build process for the `waf_benchmark` executable, including source files, compile options, and library linking. LTO is enabled conditionally.

```cmake
file(GLOB_RECURSE LIBDDWAF_BENCHMARK_SOURCE *.cpp)

add_executable(waf_benchmark ${LIBDDWAF_BENCHMARK_SOURCE})
target_compile_options(waf_benchmark PRIVATE $<$<BOOL:${LIBDDWAF_ENABLE_LTO}>:-flto>)
target_link_libraries(waf_benchmark PRIVATE libddwaf_objects lib_yamlcpp lib_rapidjson m)
target_include_directories(waf_benchmark PRIVATE ${libddwaf_SOURCE_DIR}/src)
```

--------------------------------

### Initialize WAF Context without Allocator in v1.x

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-latest.md

In v1.x, ddwaf_context_init did not require an output allocator.

```c
ddwaf_handle handle = ...;

// Create context without allocator
ddwaf_context context = ddwaf_context_init(handle);
```

--------------------------------

### Update and Build DDWAF Handle

Source: https://github.com/datadog/libddwaf/blob/master/docs/c-api/binding-integration-guide.md

Demonstrates updating configurations and building a new DDWAF handle. Ensure to destroy the old handle when it's no longer needed.

```c++
ddwaf_handle old_handle = cur_ddwaf_handle;

ddwaf_builder_add_or_update_config(builder, "main", 4, ruleset, diagnostics);
ddwaf_handle new_handle = ddwaf_builder_build_instance(builder);

cur_ddwaf_handle = new_handle;
ddwaf_destroy(old_handle);
// write lock released on return
```

--------------------------------

### Get Known Addresses

Source: https://github.com/datadog/libddwaf/blob/master/docs/c-api/api.md

Retrieves an array of all addresses known to the WAF, including required and optional ones. The returned array is invalidated by ddwaf_destroy. This function is not thread-safe.

```c
const char *const * ddwaf_known_addresses(const ddwaf_handle handle, uint32_t * size)
```

--------------------------------

### Build New WAF Instance and Destroy Old One

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-v1.x.md

After updating configurations, build a new WAF instance. The old instance can be destroyed if no longer needed, allowing both to coexist if necessary.

```cpp
ddwaf_handle new_handle = ddwaf_builder_build_instance(&builder)
if (new_handle == NULL) {
    // handle failure
}
ddwaf_destroy(&handle);
```

--------------------------------

### Get DDWAF Configuration Paths

Source: https://github.com/datadog/libddwaf/blob/master/docs/c-api/api.md

Retrieves loaded configuration paths from a builder, with optional regex filtering. The caller must free the returned object's memory.

```c
uint32_t ddwaf_builder_get_config_paths(ddwaf_builder builder, ddwaf_object * paths, const char * filter, uint32_t filter_len)
```

--------------------------------

### Example of a Test Expected to Fail but Passed

Source: https://github.com/datadog/libddwaf/blob/master/validator/README.md

Output indicating that a test, which was expected to fail, actually passed. This is considered a test failure and will result in a non-zero exit code.

```text
tests/rule9_001.yaml => Expected to fail but passed

```

--------------------------------

### Instantiate a user allocator

Source: https://github.com/datadog/libddwaf/blob/master/docs/allocators.md

This code initializes a user allocator with custom allocation and deallocation functions, user data, and a free function for the user data.

```c++
counting_allocator udata;
ddwaf_allocator alloc = ddwaf_user_allocator_init(&counting_allocator_alloc, &counting_allocator_free, &udata, &counting_allocator_udata_free);
```

--------------------------------

### Incremental Processor Overrides Configuration

Source: https://github.com/datadog/libddwaf/blob/master/docs/changelog/CHANGELOG-v1.x.md

Example of processor overrides allowing incremental additions or removals of scanners. This is a breaking change introduced in v1.29.0, but processor overrides are not currently in use.

```json
{
  "processor_overrides": [
    {
      "target": [{ "id": "extract-content" }],
      "scanners": {
        "include": [{ "id": "scanner-001" }],
        "exclude": [{ "tags": { "type": "email" } }]
      }
    }
  ]
}
```

--------------------------------

### Create Array (v1.x)

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-latest.md

In v1.x, create an array using ddwaf_object_array and add elements using ddwaf_object_array_add. Remember to free the array.

```c
ddwaf_object array;
ddwaf_object_array(&array);

// Create value objects and add to array
ddwaf_object elem1;
ddwaf_object_string(&elem1, "first");
ddwaf_object_array_add(&array, &elem1);

ddwaf_object elem2;
ddwaf_object_string(&elem2, "second");
ddwaf_object_array_add(&array, &elem2);

ddwaf_object_free(&array);
```

--------------------------------

### Get Filtered Configuration Paths with Regex in libddwaf

Source: https://github.com/datadog/libddwaf/blob/master/docs/changelog/CHANGELOG-v1.x.md

Call `ddwaf_builder_get_config_paths` with a regular expression filter to retrieve only matching configuration paths. The `LSTRARG` macro is used for string literal arguments.

```c
ddwaf_builder builder = ddwaf_builder_init(nullptr);
ddwaf_builder_add_or_update_config(builder, LSTRARG("ASM_DD/default"), &default_config, nullptr);
ddwaf_builder_add_or_update_config(builder, LSTRARG("ASM/custom_rules"), &other_config, nullptr);
ddwaf_object_free(&default_config);
ddwaf_object_free(&custom_Rules);

ddwaf_object paths;
uint32_t count = ddwaf_builder_get_config_paths(builder, &paths, LSTRARG("^ASM_DD/.*\\"));

// count: 1
// paths: [ "ASM_DD/default" ]
```

--------------------------------

### Create Map (v2.x)

Source: https://github.com/datadog/libddwaf/blob/master/docs/upgrading/UPGRADING-latest.md

v2.x requires an allocator for map creation using ddwaf_object_set_map. Keys can be inserted and values set directly using ddwaf_object_insert_key and ddwaf_object_set_string/ddwaf_object_set_unsigned.

```c
ddwaf_allocator alloc = ddwaf_get_default_allocator();

ddwaf_object map;
ddwaf_object_set_map(&map, 2, alloc);  // Initialize with capacity

// Insert key and get pointer to value, then set value directly
ddwaf_object_set_string(
    ddwaf_object_insert_key(&map, "user", 4, alloc),
    "username", 8, alloc);

// Insert another key-value pair
ddwaf_object_set_unsigned(
    ddwaf_object_insert_key(&map, "user_id", 7, alloc),
    12345);

ddwaf_object_destroy(&map, alloc);
```