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

> Contribute to the AI-Infra-Guard project by forking the Tencent AI-Infra-Guard repo, setting up Go and Python, testing changes, and submitting a pull request.

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

---

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

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

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

```bash
go test ./...

```

### YAML Schema Validation

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

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

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

```bash
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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/README.md), [`AGENTS.md`](https://github.com/Tencent/AI-Infra-Guard/blob/main/AGENTS.md), or [`api.md`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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:

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

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

```yaml
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:

```bash
./yamlcheck data/vuln

```

### Testing Python Scanner Changes

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

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

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

```bash
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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/main.py) with the `--repo` flag pointing to a test directory:

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