# What DSL Is Used for Fingerprint Rules in AI-Infra-Guard? A YAML-Driven Guide

> Discover the YAML DSL for fingerprint rules in Tencent AI-Infra-Guard. Learn how to define boolean matchers and regex extractors for effective security.

- Repository: [Tencent/AI-Infra-Guard](https://github.com/tencent/AI-Infra-Guard)
- Tags: deep-dive
- Published: 2026-08-22

---

**TLDR: Tencent/AI-Infra-Guard uses a custom YAML-based Domain-Specific Language (DSL) for fingerprint rules, parsed by the Go package `common/fingerprints/parser`, which supports boolean matchers for HTTP body, header, icon-hash, and status code checks, plus regex-based version extractors.**

## Understanding the Fingerprint DSL in AI-Infra-Guard

As implemented in Tencent/AI-Infra-Guard, fingerprint rules are not written in a general-purpose language like JSON or plain Go structs. Instead, the repository defines its own **YAML-based DSL** — a compact, declarative rule language designed specifically for identifying AI infrastructure components over HTTP. The DSL is parsed at runtime by the `common/fingerprints/parser` package, turning YAML definitions into executable rule objects.

Every fingerprint rule file in the `data/fingerprints/` directory follows this same DSL structure, making the system **deterministic, extensible, and easy to author**. If you want to detect a new service, you simply create a new YAML file using the DSL keys described below.

## The Three Core Sections of the Fingerprint DSL

The DSL organizes each fingerprint rule into distinct sections. Understanding these sections is essential for writing or modifying fingerprint definitions.

### The `info` Section

This section holds human-readable metadata about the fingerprint. It includes fields like:

- `name` — the unique identifier for the service
- `author` — the rule author
- `severity` — a label like `info`, `warning`, or `critical`
- `desc` — a description of the target service
- `metadata` — optional key-value pairs for additional context

### The `http` Section

The `http` section defines one or more HTTP probes sent to the target service. Each probe declares an HTTP `method` (GET, POST, etc.), a `path` endpoint, and a list of `matchers` — boolean expressions that evaluate the response.

### Custom Sections for Version Extraction

The `version` section (and similar custom blocks) defines extraction rules that pull version numbers or other data from a response. This relies on an `extractor` object with three fields: `part`, `group`, and `regex`.

## Matchers: The Core Expression Language

**Matchers are boolean expressions** that evaluate the response of a probe. The parser's source code confirms that the DSL "supports body/header/icon-hash matching with boolean expressions" — a capability explicitly noted in the [`CODEBUDDY.md`](https://github.com/Tencent/AI-Infra-Guard/blob/main/CODEBUDDY.md) documentation.

### Supported Matcher Primitives

The matcher primitives typically test these response parts:

- `body` — HTTP response body content
- `header` — HTTP response headers
- `icon_hash` — favicon hash values
- `status` — HTTP status code
- Other custom parts as defined by the parser

Here is a concrete example from [`data/fingerprints/vllm.yaml`](https://github.com/Tencent/AI-Infra-Guard/blob/main/data/fingerprints/vllm.yaml):

```yaml
matchers:
  - body="{\"version\":\""
  - header="uvicorn" && body="\"object\"" && body="\"data\""

```

### Logical Operators in Matchers

The DSL supports three boolean operators combined into expressions:

- `&&` — AND
- `||` — OR
- `!` — NOT

You can nest operations with parentheses. For a logical combination, you might write:

```yaml
http:
  - method: GET
    path: '/status'
    matchers:
      - header="server" && (body="ready" || body="alive")

```

## Extractors: Pulling Values with Regex

When you need to capture a version or other value from the response, the DSL's `extractor` mechanism uses a regular-expression based approach. The extractor defines:

- `part` — which response part to search (e.g., `body`)
- `group` — which capture group to return
- `regex` — the regular expression pattern

Example from [`vllm.yaml`](https://github.com/Tencent/AI-Infra-Guard/blob/main/vllm.yaml):

```yaml
extractor:
  part: body
  group: 1
  regex: '{"version":"(\d+\.\d+\.?\d+?)'

```

## HTTP Methods and Paths in Probes

Each HTTP probe within the `http` section specifies the `method` (GET, POST, etc.) and the endpoint to query. Common paths in the AI-Infra-Guard rules include `/version`, `/v1/models`, `/status`, and other service-specific routes. The parser evaluates each probe in sequence; any successful matcher indicates a fingerprint match.

## Concrete DSL Examples from the Source

### Detecting a vLLM Service

Let's examine the full vLLM fingerprint rule as shipped in [`data/fingerprints/vllm.yaml`](https://github.com/Tencent/AI-Infra-Guard/blob/main/data/fingerprints/vllm.yaml), showing the connection between the DSL sections:

```yaml
info:
  name: vllm
  severity: info
  desc: High-performance LLM inference engine
http:
  - method: GET
    path: '/version'
    matchers:
      - body="{\"version\":\""
  - method: GET
    path: '/v1/models'
    matchers:
      - header="uvicorn" && body="\"object\"" && body="\"data\""
version:
  - method: GET
    path: '/version'
    extractor:
      part: body
      group: 1
      regex: '{"version":"(\d+\.\d+?\.?\d+?)'

```

This rule shows exactly how the DSL combines the `info`, `http`, and `version` sections to identify and version the backend service.

## Key Source Files for the DSL

| File | Role |
|---|---|
| [`common/fingerprints/parser/parser.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/fingerprints/parser/parser.go) | The Go lexer/parser that sees the DSL and turns it into executable rule objects. It implements the boolean-expression matching logic discussed above. |
| [`data/fingerprints/vllm.yaml`](https://github.com/Tencent/AI-Infra-Guard/blob/main/data/fingerprints/vllm.yaml) | Concrete fingerprint example that demonstrates the DSL syntax: matchers, extractor, and HTTP probe. |
| [`CODEBUDDY.md`](https://github.com/Tencent/AI-Infra-Guard/blob/main/CODEBUDDY.md) | Describes the DSL parser capabilities, confirming it "supports body/header then icon-hash matching with boolean expressions." |
| [`README.md`](https://github.com/Tencent/AI-Infra-Guard/blob/main/README.md) | States that all fingerprint rules are YAML files under `data/fingerprints/` compiled by the custom DSL parser. |

## Summary

- **AI-Infra-Guard uses a custom YAML-based DSL**, defined by the `common/fingerprints/parser` Go package.
- The DSL has **three core sections**: `info`, `http`, and version/extractor blocks.
- **Matchers support boolean expressions** with `&&`, `||`, `!`, and parentheses over body, header, icon-hash, and status parts.
- **Extractors** use `part`, `group`, and `regex` fields to pull values like a version number from the response.
- To add a new fingerprint, just create a new YAML file with the same keys — no Go code changes are required.

## Frequently Asked Questions

### What file extension do AI-Infra-Guard fingerprint rules use?

Fingerprint rules are YAML files. All rules live under `data/fingerprints/` — for instance, the vLLM service rule is in [`data/fingerprints/vllm.yaml`](https://github.com/Tencent/AI-Infra-Guard/blob/main/data/fingerprints/vllm.yaml). The parser in `common/fingerprints/parser` compiles these `.yaml` files into executable rule objects.

### What operators can you use in the DSL matchers?

The DSL supports `&&` (AND), `||` (OR), and `!` (NOT) logical operators. You can also nest expressions in parentheses. For example, `header="server" && (body="ready" || body="alive")` is a valid matcher expression.

### How does the DSL detect a service's version?

The `version` section uses an `extractor` with three fields: `part` (which response part to search), `group` (the regex capture group), and `regex` (the pattern itself). The extractor captures the matching value — like a version string — directly from the HTTP response.

### Do you need to modify Go code to add a new fingerprint rule?

No. The DSL is fully declarative — adding a new fingerprint only requires creating a new YAML file in `data/fingerprints/` following the `info`, `http`, and optional `version` structure. The parser handles all the execution logic for you.