How to Contribute to the AI-Infra-Guard Project: A Complete Hybrid-Stack Guide

Fork the Tencent/AI-Infra-Guard repository, configure your Go (≥1.22) and Python environments, validate changes with go test, yamlcheck, and smoke tests, then submit a Pull Request targeting the main branch.

AI‑Infra‑Guard (A.I.G) is an open‑source AI security platform maintained by Tencent Zhuque Lab that combines a Go‑based core with Python scanning modules and YAML rule definitions. Understanding its hybrid architecture is essential before submitting code changes. This guide walks you through the exact contribution workflow, from environment setup to CI validation, using the specific file paths and commands defined in the source repository.

Understanding the AI-Infra-Guard Architecture

AI‑Infra‑Guard organizes its codebase into three distinct layers. Knowing where each component lives ensures you modify the correct files and follow the established patterns.

Go-Based Core Components

The backend engine and CLI reside in the Go codebase. Key locations include:

• cmd/cli/main.go – Entry point for the command‑line interface and web server
• cmd/agent/ – Agent orchestration logic
• common/websocket/ – WebSocket communication utilities
• pkg/httpx/ – Shared HTTP scanning utilities

Python Scanning Modules

Independent scanners handle AI‑specific security checks:

• mcp-scan/ – Model Context Protocol (MCP) security scanner
• agent-scan/ – AI Agent workflow security analyzer
• AIG-PromptSecurity/ – Prompt injection and jailbreak detection

Each module contains its own requirements.txt and main.py entry point.

YAML Rule Data

Security intelligence is stored as declarative YAML files:

• data/fingerprints/ – Component identification signatures
• data/vuln/ – Vulnerability detection rules (CVE-based)
• data/mcp/ – MCP plugin definitions
• data/eval/ – Jailbreak evaluation datasets

Rules must pass schema validation via the cmd/yamlcheck tool before merging.

Setting Up Your Development Environment

Proper local configuration prevents CI failures and ensures cross‑language compatibility.

Install Required Toolchains

1. Go: Install version 1.22 or higher from the official Go website.
2. Python: Use Python 3.9+ and ensure pip is available.

Build the Go Core

Clone your fork and verify the core compiles:

git clone https://github.com/<your-username>/AI-Infra-Guard.git
cd AI-Infra-Guard
go build -o ai-infra-guard ./cmd/cli/main.go

Successful compilation produces the ai-infra-guard binary without errors.

Install Python Dependencies

Each scanner runs independently. Install all required packages:

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

Running Tests Before Contributing

AI‑Infra‑Guard enforces quality gates through three validation layers. Run these locally to catch issues before opening a Pull Request.

Go Unit Tests

Execute the full Go test suite:

go test ./...

YAML Schema Validation

Build and run the internal YAML linter to check rule syntax:

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

This validates that fingerprint and vulnerability definitions conform to the expected schema in data/.

Python Smoke Tests

Verify that modified scanners still execute without runtime errors:

python agent-scan/main.py --repo .

Replace agent-scan with mcp-scan or AIG-PromptSecurity as needed.

How to Submit Your Contribution

Follow this standardized workflow to ensure your changes align with the project's CI/CD pipeline.

Forking and Branching

Create a personal fork via GitHub, then clone and branch:

git checkout -b feat/your-feature-name

Use descriptive branch names with prefixes like feat/, fix/, or docs/.

Making Code Changes

Select the appropriate modification path based on your goal:

• Adding detection rules: Create a .yaml file in data/vuln/ or data/fingerprints/ using snake_case naming. Follow existing schema patterns (see data/vuln/example-vuln.yaml for reference).
• Extending scanners: Modify Python files in mcp-scan/, agent-scan/, or AIG-PromptSecurity/, then add a smoke test script.
• Core logic changes: Edit Go packages under pkg/ or CLI commands under cmd/cli/.
• Documentation: Update README.md, AGENTS.md, or api.md. Maintain bilingual comments where the original uses both English and Chinese.

Local Validation

Re‑run the relevant test suites:

• For Go changes: go test ./...
• For YAML additions: ./yamlcheck data/vuln
• For Docker changes: docker-compose -f docker-compose.images.yml up -d

Confirm the web UI loads at http://localhost:8088 after building:

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

Opening a Pull Request

Push your branch and open a Pull Request targeting the main branch:

git add <changed-files>
git commit -m "feat: add description of changes"
git push origin feat/your-feature-name

The CI pipeline automatically executes Go tests, YAML lint checks, and Docker builds. Reviewers from Tencent Zhuque Lab evaluate contributions after all checks pass.

Contribution Examples by Task Type

These runnable examples demonstrate common contribution patterns.

Adding a New Vulnerability Rule

Create a YAML file in data/vuln/ with this structure:

id: CVE-2024-XXXX
title: Example Component Remote Code Execution
description: |
  The component allows arbitrary command execution when a crafted
  HTTP request contains a malicious `cmd` parameter.
severity: critical
affected:
  - name: example-component
    version: ">=1.0.0, <2.0.0"
cve: CVE-2024-XXXX
reference:
  - https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-XXXX

Validate the file:

./yamlcheck data/vuln

Testing Python Scanner Changes

After modifying agent-scan/ logic, verify detection against a sample repository:

python agent-scan/main.py --repo ./my-agent-project \
    --agent_provider ./provider.yaml

The scanner will include your new rules in the generated risk report.

Rebuilding After Go Modifications

If you edited pkg/httpx/ or cmd/cli/, rebuild the binary:

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

Best Practices for Contributors

Follow naming conventions: Use snake_case for all files in data/ directories and maintain the .yaml extension consistently.

Maintain multilingual consistency: Add both English and Chinese comments when modifying code, matching the repository’s dual‑language approach found in AGENTS.md and README.md.

Never hardcode secrets: Required API keys for model scanning must be passed via environment variables. The source code explicitly avoids embedded credentials.

Check CI status: Ensure all GitHub Actions workflows pass before requesting a review; failures typically indicate missing test coverage or formatting issues in Go or YAML files.

Summary

• AI‑Infra‑Guard uses a hybrid Go/Python architecture with YAML rule definitions stored in data/.
• Environment setup requires Go ≥1.22, Python 3.9+, and dependency installation via requirements.txt files.
• Pre‑submission validation includes go test ./..., ./yamlcheck data/vuln, and Python smoke tests like python agent-scan/main.py --repo ..
• Key file paths: Edit Go code in cmd/cli/ and pkg/, Python scanners in mcp-scan/ or agent-scan/, and rules in data/fingerprints/ or data/vuln/.
• Pull Requests must target the main branch and pass automated CI checks before human review.

Frequently Asked Questions

What programming languages do I need to know to contribute?

You need Go (for the core server, CLI, and rule engine in cmd/cli/ and pkg/) and Python (for the independent scanning modules in mcp-scan/, agent-scan/, and AIG-PromptSecurity/). YAML knowledge is required for contributing security rules to the data/ directories.

How do I validate new YAML vulnerability rules before submitting?

Build the yamlcheck tool from cmd/yamlcheck and run it against your rule directory:

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

This ensures your rule matches the schema expected by the Go rule engine.

Which branch should I target for Pull Requests?

Always target the main branch. The CI pipeline configured in the repository automatically runs Go unit tests, YAML linting, and Docker build checks against PRs submitted to this branch.

How do I test Python scanner modifications locally?

Run the scanner's main.py with the --repo flag pointing to a test directory:

python agent-scan/main.py --repo ./test-agent-project

This smoke test catches runtime regressions and confirms that new detection logic executes without import or syntax errors.

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