VulnAgent-X Research Prototype

VulnAgent-X is a research-focused multi-agent prototype for bug and vulnerability detection. It takes a local repository or diff as input, and outputs structured findings, evidence chains, localization, confidence, and experiment logs.

Core Capabilities

• Inputs: repo path or unified diff
• Workflow: screening -> context expansion -> scheduler -> router -> experts -> sceptic -> verification(stub) -> evidence fusion
• Output fields:
  • issue_type
  • location(file + line range)
  • evidence_summary
  • confidence
  • severity
  • optional_cwe
  • fix_hint
  • evidence_chain
  • counter_evidence
• Interfaces: CLI + FastAPI
• Reproducibility: pytest / mypy / ruff + Docker support

Workflow Overview

1. screening: fast suspicious-region extraction (rules + metadata signals)
2. context_expansion: fetch minimal sufficient local context around suspicious locations
3. scheduler: confidence-aware escalation policy (early_exit / expert_review / verification)
4. router_agent: choose specialist agents per suspicious region
5. semantic/security/logic: produce structured claims and evidence from different perspectives
6. sceptic_agent: generate counter-evidence and confidence penalties
7. verification: optional dynamic verification (currently a safe placeholder)
8. evidence_fusion: merge all evidence and produce final findings

Setup and Usage Tutorial

1) Environment Setup

Requirement: Python 3.11+ (higher versions also work in this prototype).

cd /Users/xiaolu/Documents/Python_code/vulnAgentX
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'

2) CLI Usage

Analyze a repository:

.venv/bin/vulnagentx analyze --repo /path/to/repo --output json

Analyze a diff file:

.venv/bin/vulnagentx analyze --diff-file /path/to/patch.diff --output json

Short summary output:

.venv/bin/vulnagentx analyze --repo /path/to/repo --output summary

3) API Usage

Start server:

.venv/bin/uvicorn vulnagentx.app.api:app --reload

Health check:

curl http://127.0.0.1:8000/health

Run analysis request:

curl -X POST http://127.0.0.1:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{"repo_path":"/path/to/repo"}'

4) Run with Docker

docker compose -f docker/docker-compose.yml up --build

5) Quality Checks and Tests

.venv/bin/ruff check src tests
.venv/bin/mypy src
.venv/bin/pytest

Output Example

{
  "run_id": "...",
  "findings": [
    {
      "issue_type": "command_injection",
      "location": {"file_path": "app.py", "start_line": 42, "end_line": 42},
      "evidence_summary": "Command execution surface detected...",
      "confidence": 0.87,
      "severity": "critical",
      "optional_cwe": "CWE-78",
      "fix_hint": "Avoid shell command composition...",
      "source_agents": ["security_agent", "semantic_agent"],
      "evidence_chain": [],
      "counter_evidence": []
    }
  ],
  "metrics": {
    "runtime_seconds": 0.07
  },
  "logs": []
}

File-by-File Purpose

Root and Infrastructure Files

File	Purpose
.env.example	Environment template for optional runtime settings (for example log level).
pyproject.toml	Build system, dependencies, script entrypoints, pytest/ruff/mypy configuration.
README.md	Main README with language switch buttons (default Chinese).
README.zh.md	Full Chinese documentation.
README.en.md	Full English documentation.
docker/Dockerfile	Container image build file for API service.
docker/docker-compose.yml	One-command local container startup.
rules/semgrep/vulnagentx-rules.yml	Built-in Semgrep rules for injection/deserialization/unsafe C APIs.
scripts/run_experiment.py	Batch dataset runner that writes JSONL predictions.
scripts/evaluate.py	Metrics evaluator for experiment outputs.
scripts/run_ablation.py	Component ablation runner (no_semgrep/no_treesitter/no_sceptic/no_verification).

Core Source Files (src/vulnagentx)