VAR — Vulnerabilities Autonomously Remediated

An open-source, multi-agent platform that automatically analyzes, plans, patches, validates, and raises pull requests for security vulnerabilities across your organization's repositories.

---

What is VAR?

VAR orchestrates a pipeline of specialized agents that turn a raw vulnerability scan into a merged pull request — with a human-approval gate before any code is pushed.

Scan (Snyk/Trivy)
      │
      ▼
 Vuln Parser  →  Dep Graph  →  Planner (Claude)  →  Fix Agent
                                                        │
                                              Build / Test Validator
                                                        │
                                               Git / PR Service  →  PR opened
                                                        │
                                           [Human Approval Gate]

The Campaign Orchestrator is the single coordinator — agents never talk to each other. All state lives in the Orchestrator; agents receive jobs from a queue and publish results back.

---

Key Features

• Fully automated fix pipeline — Analyze → Plan → Patch → Build → Validate → PR, all hands-free
• Human-in-the-loop gates — Slack/webhook approval required before any code reaches your SCM
• LLM-powered remediation planning — Uses Claude (Anthropic) to generate context-aware fix strategies, with support for any OpenAI-compatible endpoint
• Dependency blast-radius analysis — Neo4j graph database maps transitive dependency impact before any patch is applied
• Multi-scanner ingest — Parses Snyk and Trivy reports; extensible base for other scanners
• Multi-SCM — GitHub (App auth) and Bitbucket (app password) out of the box
• Audit trail — Every decision, approval, and action stored in PostgreSQL with full correlation_id tracing
• JIRA, Slack, Syslog — Notification integrations included
• Evidence storage — Build logs and scan artifacts stored in S3/MinIO

---

Architecture

VAR uses a Hybrid Orchestrator + Queue pattern (see ADR-001):

• The Campaign Orchestrator is the only externally-facing service (REST API on port 8000)
• All inter-agent coordination flows through Redis Streams (swappable for SQS)
• Agents are independently deployable and replaceable — adding a new agent = new queue topic pair + one state machine registration
• Long-running operations (patch, build, scan) are non-blocking by default

Services

Service	Description
orchestrator	Campaign state machine, REST API, human approval endpoints
vuln-parser	Ingests Snyk / Trivy reports, normalizes vulnerabilities
dep-graph	Crawls repos, builds Neo4j dependency graph, computes blast radius
planner	LLM agent that produces structured remediation plans per repo
fix-agent	Applies patches in an isolated Docker sandbox, commits changes
validator	Runs the target repo's build + tests inside Docker to confirm fix
git-pr	Opens pull requests via GitHub App or Bitbucket
ui	React/TypeScript dashboard (served on port 3000)

Infrastructure

Component	Purpose
PostgreSQL 16	Campaign state, vulnerabilities, audit log
Redis 7	Job queue (Redis Streams with AOF persistence)
Neo4j 5	Dependency graph and blast-radius traversal
MinIO / S3	Evidence and build log storage

---

Quick Start

Prerequisites

• Docker & Docker Compose
• An Anthropic API key (or any OpenAI-compatible endpoint)
• A GitHub App (for SCM operations) — see GitHub App Setup

1. Clone and configure

git clone https://github.com/YOUR_ORG/VAR.git
cd VAR
cp .env.example .env
# Edit .env — at minimum set ANTHROPIC_API_KEY and GitHub App credentials

2. Start everything

make up

Services start at:

• Orchestrator API + Swagger UI: http://localhost:8000/docs
• Dashboard UI: http://localhost:3000
• Neo4j Browser: http://localhost:7474
• MinIO Console: http://localhost:9001

3. Run migrations

make migrate

4. Ingest a scan

curl -X POST http://localhost:8000/api/v1/campaigns \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 Security Sprint",
    "scanner": "snyk",
    "report_url": "s3://var-evidence/reports/snyk-report.json"
  }'

---

Configuration

All configuration is via environment variables. Copy .env.example to .env and fill in:

Variable	Description
ANTHROPIC_API_KEY	Anthropic API key for Claude
LLM_PROVIDER	anthropic or openai_compatible
LLM_BASE_URL	Base URL for OpenAI-compatible endpoints (optional)
GITHUB_APP_ID	GitHub App ID
GITHUB_APP_PRIVATE_KEY_PATH	Path to GitHub App private key PEM
POSTGRES_*	PostgreSQL connection settings
REDIS_URL	Redis connection URL
NEO4J_URI / NEO4J_USER / NEO4J_PASSWORD	Neo4j connection settings
JIRA_*	JIRA integration (optional)
SLACK_WEBHOOK_URL	Slack notifications (optional)
S3_* / AWS_*	S3 / MinIO evidence storage

See .env.example for the full list with descriptions.

---

GitHub App Setup

1. Create a GitHub App in your organization with permissions:
   • Contents: Read & Write
   • Pull requests: Read & Write
   • Metadata: Read
2. Download the private key PEM and place it at secrets/github_app.pem
3. Set GITHUB_APP_ID in .env

---

Development

Install dependencies

make install   # installs all Python packages in editable mode via uv

Lint and type-check

make lint      # ruff + mypy

Run tests

make test

Run infrastructure only (no VAR services)

make infra

Tail logs

make logs

---

Project Structure

VAR/
├── services/
│   ├── orchestrator/    # Campaign Orchestrator (FastAPI, state machine)
│   ├── vuln-parser/     # Vulnerability ingest and normalization
│   ├── dep-graph/       # Dependency graph agent (Neo4j)
│   ├── planner/         # LLM remediation planner (Claude)
│   ├── fix-agent/       # Code patcher (sandboxed Docker exec)
│   ├── validator/       # Build + test validator
│   ├── git-pr/          # Git / PR service
│   └── ui/              # React + TypeScript dashboard
├── packages/
│   └── var-core/        # Shared schemas, DB models, queue helpers
├── migrations/          # Alembic database migrations
├── docs/
│   ├── adr/             # Architecture Decision Records
│   └── api-design/      # API contracts per service
├── docker-compose.yml
├── Makefile
└── .env.example

---

API

The Orchestrator exposes a REST API at /api/v1/. Interactive docs available at http://localhost:8000/docs when running locally.

Key endpoints:

Method	Path	Description
POST	/api/v1/campaigns	Create a new remediation campaign
GET	/api/v1/campaigns/{id}	Get campaign status and timeline
POST	/api/v1/campaigns/{id}/approve-plan	Approve the remediation plan (HIL gate)
POST	/api/v1/campaigns/{id}/approve-pr	Approve the pull request (HIL gate)
GET	/api/v1/vulnerabilities	List all known vulnerabilities
GET	/api/v1/audit	Audit log
POST	/api/v1/scans	Trigger a new scan

Full API contracts are in docs/api-design/.

---

Architecture Decision Records

Design decisions are documented in docs/adr/:

• ADR-001 — Agent communication: Hybrid Orchestrator + Queue
• ADR-002 — Graph storage: Neo4j
• ADR-003 — Sandbox isolation for code patching
• ADR-004 — API versioning strategy
• ADR-005 — Authentication: mTLS + OIDC
• ADR-006 — LLM choice
• ADR-007 — Queue technology: Redis Streams
• ADR-008 — Tenancy model
• ADR-009 — Compliance integrations

---

Contributing

Contributions are welcome. Please open an issue before submitting a large PR so we can align on direction.

1. Fork the repo
2. Create a feature branch (git checkout -b feat/my-feature)
3. Commit your changes
4. Open a pull request

---

License

MIT — see LICENSE.