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

> Learn how to configure AI-Infra-Guard for specific use cases. Customize scans for single services, multiple targets, or web deployments using CLI flags, environment variables, or custom rules.

- Repository: [Tencent/AI-Infra-Guard](https://github.com/tencent/AI-Infra-Guard)
- Tags: how-to-guide
- Published: 2026-08-23

---

**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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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:

```bash
./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:

```bash
./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:

```bash
./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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/cmd/cli/cmd/webserver.go) emits a security warning before starting the WebSocket backend defined in [`common/websocket/websocket.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/websocket/websocket.go).

### Integrating the Model/API Checker

Enable external model validation by configuring `APICheckerURL`:

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

```

Alternatively, set the environment variable:

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

```

The `defaultAPICheckerURL()` function in [`internal/options/options.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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:

```bash
./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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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:

```bash
./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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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:

```bash
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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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.