What Is the Role of Python Agents in AI-Infra-Guard? Security Scanning Engine Explained

The Python agents in AI-Infra-Guard serve as the core orchestration and scanning engine that automates security analysis of LLM-powered services through a three-stage pipeline involving information collection, parallel vulnerability detection, and structured report generation.

The Tencent AI-Infra-Guard project delivers an open-source security framework specifically designed to assess the safety posture of AI agents and LLM-powered infrastructure. At the heart of this system lies a Python-based agent framework that executes automated security assessments against target services. These Python agents function as both orchestrators and workers, driving the entire vulnerability detection lifecycle while the Go backend handles UI coordination and persistence.

Three-Stage Security Scanning Pipeline

The Python agents implement a sophisticated pipeline defined in agent_scan/core/agent.py that systematically analyzes AI service security postures.

Stage 1 – Information Collection and Reconnaissance

The scanning process begins when the Agent.scan method initiates ScanPipeline.execute_stage with the project_summary prompt. This reconnaissance phase gathers critical target configuration details, exposed endpoints, and language-specific metadata to establish the attack surface baseline before vulnerability testing commences.

Stage 2 – Parallel Vulnerability Detection

During the detection phase, the framework spawns lightweight skill-workers for every detection skill—such as data-leakage, tool-abuse, or web-exfiltration checks. The ScanPipeline.run_parallel_detection method orchestrates these workers under a semaphore to prevent rate-limit exhaustion, with each worker invoking run_agent using a skill_runner prompt. This parallel architecture enables concurrent security testing without overwhelming target systems or API quotas.

Stage 3 – Vulnerability Review and Taxonomy Mapping

The final stage invokes ScanPipeline.execute_stage once more, this time with the agent_security_reviewer prompt. This reviewer-agent consolidates <vuln> XML blocks discovered during detection, maps findings to the OWASP ASI (Agentic Security Intelligence) taxonomy, and assigns severity ratings to produce actionable, standardized intelligence.

Core Architecture and Components

The Python agent subsystem comprises several specialized modules that coordinate LLM interactions and security testing logic.

LLM Integration and Provider Configuration

The Python agents interact with LLM backends through the agent_scan.utils.llm.LLM class, which supports multiple providers including OpenAI and OpenRouter. The system consumes a provider configuration file (provider.yaml) via the AIProviderClient adapter to establish connections with live AI services, enabling dynamic switching between specialized LLMs for thinking, coding, and analysis tasks.

Skill-Based Detection System

Security checks are implemented as reusable skills stored under agent_scan/prompt/skills/*/. Each skill contains a SKILL.md prompt file defining a specific security check—such as "web-exfiltration-detection" or "credential-leakage-scan". The framework dynamically discovers and executes these skills as parallel workers, allowing extensible security testing without modifying core agent code in agent_scan/core/agent.py.

Structured Report Generation

Upon completion, the agents generate SARIF-compatible reports through generate_report_from_xml implemented in agent_scan/core/report.py. These structured outputs can be consumed by the Go backend for persistence or exported as JSON for integration with external security information and event management systems.

Practical Implementation Examples

Command-Line Scanning

Execute standalone security scans using the CLI entry point defined in agent_scan/main.py:

aig-agent-scan --repo /path/to/project \
               --prompt "Focus on secret leakage" \
               --model gpt-4o-mini \
               --api_key $OPENAI_API_KEY \
               --language en \
               --output result.json

Programmatic Agent Integration

Import the Agent class directly for custom automation workflows:

import asyncio
from agent_scan.core.agent import Agent
from agent_scan.utils.llm import LLM

# Initialise the primary LLM (override with your own API key/model)

llm = LLM(model="gpt-4o-mini", api_key="YOUR_KEY", base_url="https://api.openai.com/v1")
agent = Agent(llm=llm, language="en", agent_provider="providers.yaml")

async def run():
    report = await agent.scan(repo_dir="/path/to/project", prompt="Check for credential leakage")
    print(report["language"], report["summary"])

asyncio.run(run())

Custom Detection Skill Development

Extend the framework by creating new detection capabilities under agent_scan/prompt/skills/:

# Create a custom skill folder with SKILL.md, then invoke:

aig-agent-scan --repo . --skills my-custom-check

The framework automatically discovers the skill via the skills argument and executes it as a parallel worker alongside built-in checks.

Summary

• The Python agents in AI-Infra-Guard implement a three-stage pipeline (reconnaissance, parallel detection, review) for automated security assessment of LLM services.
• The architecture centers on agent_scan/core/agent.py, where Agent.scan and ScanPipeline classes orchestrate concurrent skill execution.
• Skill-based detection allows modular security checks stored as prompts in agent_scan/prompt/skills/*/SKILL.md.
• The system generates SARIF-compatible reports via agent_scan/core/report.py for integration with security workflows.
• Python agents handle the core scanning logic while the Go backend manages UI, WebSocket coordination, and data persistence.

Frequently Asked Questions

How do Python agents differ from the Go backend in AI-Infra-Guard?

The Python agents constitute the actual security scanning engine that performs vulnerability detection, LLM interaction, and report generation. The Go backend provides the user interface, WebSocket server for real-time communication, CLI coordination, and persistence layer. While Go handles orchestration and delivery, Python executes the core analytical work according to the source code architecture.

Can Python agents in AI-Infra-Guard scan non-Python AI services?

Yes. The Python agents are language-agnostic regarding their targets. Through the AIProviderClient adapter and configurable provider.yaml, they can assess any LLM-powered service regardless of the target's implementation language, analyzing exposed endpoints and behaviors rather than source code alone.

What is the purpose of the semaphore in the parallel detection stage?

The semaphore in ScanPipeline.run_parallel_detection limits concurrent skill-worker execution to prevent rate-limit exhaustion on target services and LLM APIs. This throttling mechanism ensures responsible scanning that respects API quotas while maintaining efficiency through parallel processing.

How does the agent framework map vulnerabilities to security standards?

During the review stage, the agent_security_reviewer prompt processes discovered <vuln> XML blocks and maps them to the OWASP ASI (Agentic Security Intelligence) taxonomy. This classification occurs in agent_scan/core/agent.py during the final ScanPipeline.execute_stage call, standardizing findings for security teams.

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