How to Configure AI‑Infra‑Guard for Specific Use Cases: A Complete Guide

Configure AI‑Infra‑Guard by modifying the options.Options struct through CLI flags, environment variables, or custom rule directories to tailor scans for single services, multiple targets, or integrated web deployments.

AI‑Infra‑Guard (A.I.G) from Tencent is an open-source security scanning platform designed for AI infrastructure. Learning how to configure AI‑Infra‑Guard for specific environments—whether scanning a local vLLM instance or deploying the full web interface—requires familiarity with its Go-based CLI entry points and Python scan modules. This guide examines the actual source implementation to provide precise configuration strategies based on the repository structure.

Core Configuration Architecture

The options.Options Struct

All runtime behavior in AI‑Infra‑Guard centers on the options.Options struct defined in internal/options/options.go. This struct aggregates CLI flags, environment variables, and file paths into a single configuration object consumed by the scanning engine.

Key configuration fields include:

• Target and TargetFile for specifying scan destinations
• FPTemplates and AdvTemplates for custom rule directories
• ProxyURL, TimeOut, and RateLimit for network tuning
• WebServer and WebServerAddr for UI deployment
• APICheckerURL for external model validation services
• Headers for custom HTTP authentication
• Language for UI localization (zh or en)

The CLI binary located at cmd/cli/main.go parses these options and dispatches to subcommands like scan or webserver.

CLI Entry Points

The primary entry point ai-infra-guard in cmd/cli/main.go constructs the Options struct and launches the appropriate sub-command. The webserver sub-command defined in cmd/cli/cmd/webserver.go manages WebSocket initialization and accepts additional flags such as --server and --api-checker-url.

Common Configuration Scenarios

Scanning Single AI Services

To configure AI‑Infra‑Guard for scanning a specific inference endpoint like vLLM, Ollama, or ComfyUI:

./ai-infra-guard scan \
    -target http://127.0.0.1:8000 \
    -fps data/fingerprints \
    -vul data/vuln \
    -o scan-report.json \
    -json

The -target flag populates the Target field, while -fps and -vul override the default FPTemplates and AdvTemplates directories. The -json flag ensures machine-readable output suitable for CI pipelines.

Batch Scanning from Target Files

For multiple targets, populate Options.TargetFile using the -file flag:

./ai-infra-guard scan \
    -file targets.txt \
    -o multi-report.json \
    -json \
    -limit 200

The file specified by -file must contain one URL or IP address per line. The -limit flag configures the RateLimit field to throttle requests to 200 per second.

Running the WebSocket Server

To configure the web interface, use the webserver sub-command:

./ai-infra-guard webserver --server 0.0.0.0:8088

This sets the WebServerAddr field. By default, the server binds to 127.0.0.1:8088. When binding to non-loopback addresses, the implementation in cmd/cli/cmd/webserver.go emits a security warning before starting the WebSocket backend defined in common/websocket/websocket.go.

Integrating the Model/API Checker

Enable external model validation by configuring APICheckerURL:

./ai-infra-guard webserver --api-checker-url http://127.0.0.1:8000

Alternatively, set the environment variable:

export AIG_API_CHECKER_URL="http://my-checker:8000"
./ai-infra-guard webserver

The defaultAPICheckerURL() function in internal/options/options.go checks this environment variable when the flag is omitted. Disable the checker by passing an empty string: --api-checker-url "".

Using Proxy and Custom Headers

For environments requiring HTTP proxies or authentication headers:

./ai-infra-guard scan \
    -target http://remote-ai-service:8080 \
    -proxy-url http://user:pwd@proxy.mycorp.com:3128 \
    -header "Authorization: Bearer $LLM_API_KEY" \
    -header "X-Custom: value"

The validateProxyURL() function in internal/options/options.go validates proxy configurations. Multiple -header flags accumulate into the multiStringFlag slice for the Headers field.

Advanced Configuration Options

Custom Fingerprint and Vulnerability Rules

Point AI‑Infra‑Guard to custom rule sets by overriding the template directories:

./ai-infra-guard scan \
    -fps /my/custom/fingerprints \
    -vul /my/custom/vuln \
    -target http://127.0.0.1:8000

The directories must follow the YAML schema used in the bundled data/fingerprints and data/vuln folders.

Environment Variable Overrides

Beyond AIG_API_CHECKER_URL, the configuration system respects environment-based defaults for various fields. The source code in internal/options/options.go defines fallback logic where environment variables can preset values before CLI flag parsing occurs.

Python Module Configuration

The Python-based scanners (skill-scan, mcp-scan, agent-scan) consume the same data directories but offer independent CLI interfaces:

pip install aig-skill-scan
export LLM_API_KEY="my-api-key"
aig-skill-scan --repo /path/to/skill \
    -m deepseek-v4-flash \
    --language en \
    -o skill-report.json

These modules respect the data/fingerprints, data/vuln, and data/mcp hierarchies while allowing standalone execution separate from the Go binary.

Summary

• Configuration centers on options.Options: All settings flow through the struct defined in internal/options/options.go, populated via CLI flags like -target, -proxy-url, and -file.
• Web deployment uses sub-commands: The webserver command in cmd/cli/cmd/webserver.go manages WebSocket initialization and accepts --server and --api-checker-url flags.
• External integrations use environment variables: Set AIG_API_CHECKER_URL to configure the Model/API Checker endpoint without passing flags.
• Custom rules require directory paths: Override FPTemplates and AdvTemplates using -fps and -vul to use non-standard fingerprint or vulnerability definitions.
• Python modules offer stand-alone configuration: Installable via pip, these tools share data directories but use independent argument parsers for specialized scanning tasks.

Frequently Asked Questions

How do I configure AI‑Infra‑Guard to scan multiple targets simultaneously?

Use the -file flag to specify a text file containing one target URL or IP address per line. This populates the TargetFile field in the Options struct, allowing the scanner to iterate through multiple endpoints in a single execution while respecting the RateLimit configuration.

Can I run the web interface on a public network interface?

Yes, pass the --server flag with 0.0.0.0:8088 to bind to all interfaces. However, the source code in cmd/cli/cmd/webserver.go emits a security warning when binding to non-loopback addresses, as the WebSocket backend defined in common/websocket/websocket.go does not implement authentication by default.

Where does AI‑Infra‑Guard store its fingerprint and vulnerability rules?

By default, the scanner looks in data/fingerprints for service identification rules and data/vuln for vulnerability signatures. Configure alternative paths using the -fps and -vul flags to point to custom directories following the same YAML schema as the original bundles.

How do I disable the Model/API Checker integration?

Pass an empty string to the --api-checker-url flag when starting the webserver: ./ai-infra-guard webserver --api-checker-url "". Alternatively, ensure the AIG_API_CHECKER_URL environment variable is unset or empty before execution, causing the defaultAPICheckerURL() function to return an empty default.

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