How to Troubleshoot Common Issues in AI-Infra-Guard: Complete Diagnostic Guide

To troubleshoot AI-Infra-Guard effectively, verify your YAML rule files with the built-in validator, check WebSocket connectivity between agents and the server, and ensure Python dependencies are installed for scanning modules.

AI-Infra-Guard is a hybrid-stack AI security scanning platform maintained by Tencent that combines a Go-based core with Python sub-modules for extensible detection. Understanding its dual-language architecture and key file locations allows you to isolate failures quickly across the CLI, WebSocket API, database layer, and plugin systems.

Architecture Overview: Where Problems Originate

AI-Infra-Guard's codebase is organized into distinct layers. Knowing these boundaries helps you route issues to the correct subsystem immediately.

• CLI & Server Layer (cmd/cli/*, cmd/agent/*): Entry points for the web service, command-line interface, and agent processes. Crashes here usually indicate configuration errors or CGO mismatches.
• WebSocket & Task Engine (common/websocket/*): Handles real-time bidirectional communication, task scheduling, and agent registration. Disconnects and registration failures stem from this layer.
• Database & Persistence (pkg/database/*): SQLite/JSON storage for scan tasks and results. Schema mismatches appear here.
• HTTP Infrastructure (pkg/httpx/*): Unified HTTP client with customizable options. Timeout and proxy issues originate in pkg/httpx/options.go.
• Scanning Engines (internal/mcp/*, agent-scan/, mcp-scan/): Core vulnerability detection written in Go, augmented by Python plugins. Missing vulnerabilities usually indicate rule parsing failures.
• Static Rule Data (data/*): YAML/JSON fingerprint and vulnerability definitions. Corrupted files here cause silent scan failures.

Common Failure Scenarios and Diagnostics

Segmentation Faults and Binary Crashes

If you encounter ./ai-infra-guard: signal: segmentation fault, the Go binary was likely built against mismatched CGO libraries or is loading invalid configuration files.

1. Rebuild with the race detector to catch data races:

go build -race -o ai-infra-guard ./cmd/cli/main.go

2. Validate that configuration files in data/ are syntactically correct:

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

Critical files to inspect: cmd/cli/main.go for entry-point logic and pkg/database/yaml_model.go for YAML parsing errors.

WebSocket Disconnects and "Connection Lost" Errors

When the web UI displays connection errors, the WebSocket server is unreachable or behind a misconfigured proxy.

1. Confirm the server is listening on the expected address:

netstat -tlnp | grep ai-infra-guard

2. Check common/websocket/config.go for the correct bind address configuration.
3. Inspect common/websocket/server.go for server-side connection handling and common/websocket/task_manager.go for task routing issues.

Agent Registration Failures

Agents that fail to register typically cannot reach the WebSocket endpoint or have mismatched environment variables.

1. Verify the AIG_SERVER environment variable points to the correct host (e.g., 127.0.0.1:8088):

export AIG_SERVER=127.0.0.1:8088
./ai-infra-guard agent

2. Review the registration logic in common/websocket/agent.go to ensure the handshake protocol matches between client and server.

Missing Vulnerabilities in Scan Output

When scans complete but return no findings, rule files may not be loading or are outdated.

1. Run the YAML validator across all rule directories:

./yamlcheck data/fingerprints data/vuln data/vuln_en

2. Verify that pkg/database/model.go correctly parses the stored results and that internal/mcp/scanner.go is executing the rule evaluation logic.

HTTP Request Timeouts

Default timeouts may be too short for slow targets, or proxy settings may be incorrect.

1. Inspect pkg/httpx/options.go for the DefaultTimeout constant.
2. Adjust via CLI flag --timeout or environment variable HTTP_TIMEOUT.
3. For debugging, enable verbose logging in your Go code:

import (
    "github.com/Tencent/AI-Infra-Guard/pkg/httpx"
    "github.com/Tencent/AI-Infra-Guard/pkg/httpx/options"
    "time"
)

func main() {
    opts := []options.Option{
        options.WithDebug(true),
        options.WithTimeout(30 * time.Second),
    }
    client := httpx.NewClient(opts...)
    resp, err := client.Get("https://example.com")
    // Handle response
}

Key files: pkg/httpx/httpx.go and pkg/httpx/response.go.

Python Sub-module Crashes

Python-based scanners in mcp-scan/ and agent-scan/ crash when dependencies are missing.

1. Install requirements for the specific module:

pip install -r agent-scan/requirements.txt
pip install -r mcp-scan/requirements.txt

2. Execute the entry script directly to see tracebacks:

python agent-scan/main.py --help

Diagnostic Code Examples

Running a Local Scan Server and Client

Build the binary and launch the web server, then execute a scan in a separate terminal:

# Terminal 1: Build and start server

go build -o ai-infra-guard ./cmd/cli/main.go
./ai-infra-guard webserver --server 127.0.0.1:8088

# Terminal 2: Run scan

./ai-infra-guard scan -t http://127.0.0.1:8088

Relevant source files: cmd/cli/cmd/webserver.go and cmd/cli/cmd/scan.go.

Adding a Custom MCP Plugin for Testing

Create internal/mcp/plugins/my_plugin.go:

package plugins

import (
    "github.com/Tencent/AI-Infra-Guard/internal/mcp"
)

type MyPlugin struct{}

func (p *MyPlugin) Name() string { return "my-plugin" }

func (p *MyPlugin) Scan(target string) ([]mcp.Finding, error) {
    // Custom scanning logic here
    return nil, nil
}

Register it in internal/mcp/plugins.go:

func init() {
    Register(&MyPlugin{})
}

Key Source Files for Troubleshooting

Keep these file paths accessible when debugging:

• CLI Entry: cmd/cli/main.go - Top-level flag parsing and sub-command dispatch.
• Agent Process: cmd/agent/main.go - Agent startup and configuration.
• WebSocket Server: common/websocket/server.go - API implementation and SSE fallback.
• Task Coordination: common/websocket/task_manager.go - Job scheduling and cancellation.
• Database Schema: pkg/database/model.go - Entity definitions for tasks and results.
• HTTP Client: pkg/httpx/httpx.go - Request builder and response handling.
• MCP Core: internal/mcp/scanner.go - Rule evaluation orchestration.
• Rule Validation: cmd/yamlcheck/main.go - Build target for the YAML validator.
• Python Scanner: agent-scan/main.py - Python-based scan execution.
• Static Rules: data/fingerprints/ and data/vuln/ - Rule definitions requiring validation.

Summary

• Validate configurations first: Use ./yamlcheck to verify all YAML files in data/ before investigating code issues.
• Check connectivity layers: Isolate WebSocket issues by verifying AIG_SERVER environment variables and inspecting common/websocket/server.go.
• Rebuild with debug flags: Use go build -race to detect concurrency issues in the Go core.
• Verify Python environments: Ensure requirements.txt dependencies are installed for agent-scan and mcp-scan modules.
• Adjust HTTP timeouts: Modify DefaultTimeout in pkg/httpx/options.go or use --timeout flags for slow targets.

Frequently Asked Questions

How do I fix the "connection lost" error in the AI-Infra-Guard web UI?

This error indicates the WebSocket server is unreachable. Confirm the server process is running and listening on the correct port using netstat -tlnp, then verify the bind address in common/websocket/config.go matches your proxy or network configuration.

Why does AI-Infra-Guard crash with a segmentation fault on startup?

Segmentation faults typically occur due to CGO library mismatches or corrupted YAML configuration files. Rebuild the binary with go build -race ./cmd/cli/main.go to catch data races, and run ./yamlcheck against all files in data/fingerprints and data/vuln to ensure valid syntax.

How can I debug why my scan returns no vulnerabilities?

First validate your rule files are loading correctly using the YAML checker. If rules are valid, check internal/mcp/scanner.go to ensure the MCP engine is executing plugins, and verify pkg/database/model.go for proper result serialization. Also confirm the target is actually vulnerable by testing against known-vulnerable sample data.

What should I check when the AI-Infra-Guard agent fails to register with the server?

Ensure the AIG_SERVER environment variable points to the correct WebSocket endpoint (e.g., 127.0.0.1:8088). Then inspect common/websocket/agent.go for the registration handshake logic and confirm no firewall rules are blocking the WebSocket port.

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