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

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 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:

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:

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:

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, showing the connection between the DSL sections:

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	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	Concrete fingerprint example that demonstrates the DSL syntax: matchers, extractor, and HTTP probe.
CODEBUDDY.md	Describes the DSL parser capabilities, confirming it "supports body/header then icon-hash matching with boolean expressions."
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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}