How to Troubleshoot Common Issues with AI-Infra-Guard: A Complete Guide

Most operational problems in AI-Infra-Guard stem from misconfiguration, missing runtime resources, or unexpected runtime errors across its Go-based CLI, Python plugins, and WebSocket server components.

AI-Infra-Guard (AIG) is a multi-component security-scanning platform developed by Tencent that combines Go services, Python plugins, and a WebSocket-based UI. When you troubleshoot common issues with AI-Infra-Guard, understanding the specific failure points in its architecture—from option parsing in cmd/cli/main.go to database initialization in pkg/database/config.go—allows you to isolate and resolve errors rapidly.

Understanding the Component Architecture

AI-Infra-Guard consists of distinct layers where failures typically occur. The following table maps each component to its typical failure mode and source location:

Component	Function	Common Failure	Source Location
CLI Entry Point	Parses flags and launches sub-commands	Flags ignored or immediate exit with Program exiting	cmd/cli/main.go
Options Parser	Validates proxy URLs, timeouts, targets	invalid http proxy format errors	internal/options/options.go
WebSocket Server	Serves UI and streams results	Binding to non-loopback addresses or firewall blocks	cmd/cli/cmd/webserver.go
Database Layer	Persists tasks and metadata	创建数据库目录失败 (failed to create directory)	pkg/database/config.go
HTTPX Utilities	Handles outbound HTTP scanning	Timeouts and malformed responses	pkg/httpx/httpx.go
Vulnerability Engine	Loads YAML rule files	read directory error for fingerprints	pkg/vulstruct/advisory.go
MCP/Agent Scan	Executes plugin-based scans	Plugin registration failures	internal/mcp/scanner.go

Resolving Startup and CLI Validation Errors

When the binary exits immediately with gologger.Fatalf("Program exiting: …"), the Options.validateOptions() function in internal/options/options.go has detected an illegal configuration value.

Invalid Proxy URL Errors

The most common CLI failure occurs when the -proxy-url flag contains a malformed URL. The validateProxyURL function expects the format scheme://[user:pass@]host:port.

Error symptom:

invalid http proxy format …

Solution: Verify your proxy URL syntax:

ai-infra-guard scan -target http://127.0.0.1:8000 -proxy-url http://user:pwd@proxy.example.com:3128

If you do not require a proxy, omit the flag entirely or set it to an empty string to bypass validation.

Fixing WebSocket Server Binding and Connectivity Issues

The WebSocket server in cmd/cli/cmd/webserver.go validates that listening addresses contain 127.0.0.1 for security. If you specify 0.0.0.0:8088 or a public interface, the server prints a warning (lines 43-45) but still attempts to start.

Symptoms: UI cannot connect to http://localhost:8088 or "unsafe listening address" warnings appear.

Fix: Use the loop-back address explicitly:

ai-infra-guard webserver --server 127.0.0.1:8088

If you must bind to external interfaces, ensure your host firewall permits inbound traffic on the chosen port.

Troubleshooting Database Initialization and Permission Errors

Database failures originate in pkg/database/config.go where InitDB attempts to create the parent directory of the SQLite file (lines 58-61).

Symptoms: 创建数据库目录失败 or 无法打开数据库连接 errors.

Root cause: The process lacks permission to create the directory specified in DB_PATH, or the path is malformed.

Solution: Pre-create the directory with proper permissions:

export DB_PATH=$HOME/aig/db/tasks.db
mkdir -p $(dirname $DB_PATH)
chmod 755 $(dirname $DB_PATH)

If DB_PATH is unset, the default db/tasks.db resolves to the repository root, which may lack write permissions depending on your installation method.

Diagnosing Target Scanning Timeouts and HTTP Errors

Scanning failures typically manifest in pkg/httpx/httpx.go where HTTPX.do() (lines 109-122) applies the configured timeout. Unreachable targets or slow AI services trigger error reading response messages.

Resolution steps:

1. Increase the timeout threshold:

   ai-infra-guard scan -target http://127.0.0.1:8000 -timeout 30

2. Verify the target is a running AI service endpoint, not a repository URL.

3. Test connectivity independently with curl to isolate network issues from application errors.

Resolving Fingerprint and Vulnerability Rule Loading Failures

The vulnerability engine in pkg/vulstruct/advisory.go walks the data/fingerprints and data/vuln directories (line 61). Missing directories or malformed YAML trigger read directory error or "no rules found" messages.

Fix: Ensure the data/ folder exists in your working directory. Validate rule syntax using the bundled checker:

go build -o yamlcheck ./cmd/yamlcheck
./yamlcheck data/fingerprints data/vuln data/vuln_en

Place custom rules in the appropriate subdirectories and re-run the checker before executing scans.

Fixing MCP and Agent Plugin Registration Errors

Plugin failures occur in internal/mcp/scanner.go where Scanner.RegisterPlugin (line 138) validates plugin names against files in data/mcp/.

Symptoms: RegisterPlugin returns an error and the scan aborts without processing plugins.

Solution: List available plugins to verify the name exists:

ai-infra-guard mcp list

Ensure the -plugin argument matches a filename in data/mcp/ exactly.

Handling Unexpected Process Termination and Panics

Fatal exits wrapped by gologger.WithError(err).Fatalln indicate unrecoverable conditions such as corrupted databases, critical I/O failures, or missing configuration. These appear as panic or Fatalf messages with stack traces.

Fix: Examine the log line immediately preceding the stack trace to identify the resource failure—whether file permissions, environment variables, or network connectivity—and remediate the underlying condition.

General Debugging Workflow

For issues not resolved by component-specific fixes, follow this systematic approach:

1. Enable verbose logging by setting GOTRACEBACK=all to capture full stack traces.
2. Run with -v (supported by most sub-commands) to view parsed options.
3. Check container logs if deploying via Docker using docker logs <container>, as these contain the same gologger output as host processes.
4. Verify YAML integrity with the yamlcheck utility before deployment.
5. Use the API documentation at http://localhost:8088/docs/index.html to manually invoke endpoints and inspect raw JSON error responses.

Summary

• CLI validation errors in internal/options/options.go typically indicate malformed proxy URLs or missing required flags.
• WebSocket binding issues require loop-back addresses (127.0.0.1) unless you explicitly configure firewall rules for external access.
• Database failures in pkg/database/config.go result from missing parent directories or insufficient permissions for the DB_PATH location.
• Scanning timeouts in pkg/httpx/httpx.go resolve by increasing the -timeout value or verifying target service availability.
• Rule loading errors in pkg/vulstruct/advisory.go require intact data/ directories and valid YAML syntax verified by yamlcheck.
• Plugin registration in internal/mcp/scanner.go fails when plugin names do not match files in data/mcp/.

Frequently Asked Questions

Why does AI-Infra-Guard exit immediately with "Program exiting"?

The Options.validateOptions() function in internal/options/options.go detected an invalid configuration, most commonly a malformed proxy URL. Verify that -proxy-url follows the format http://user:pass@host:port or omit the flag entirely if no proxy is required.

How do I fix "cannot open database" errors when starting the scanner?

This error originates in pkg/database/config.go where InitDB cannot create the directory specified by DB_PATH. Pre-create the directory with mkdir -p $(dirname $DB_PATH) and ensure the process has write permissions, or unset DB_PATH to use the default location.

Why does my scan return "Timeout / error handling" for valid targets?

The HTTPX.do() method in pkg/httpx/httpx.go enforces the timeout specified by -timeout. Increase the timeout value for slow-responding AI services, and verify the target URL points to a running inference endpoint rather than a static repository page.

Where should I place custom fingerprint or vulnerability rules?

Place custom YAML files in data/fingerprints/ or data/vuln/ respectively, then validate them with ./yamlcheck data/fingerprints data/vuln before running scans. The loader in pkg/vulstruct/advisory.go requires these directories to exist in your working directory.

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