Vision

Zagros — Project Vision

Purpose

Zagros is an open-source, self-hosted security knowledge service for teams and their AI agents. Its purpose is to give an organization or technical team a shared, inspectable, controlled security reference that multiple humans, agents, IDE integrations, and internal tools can use consistently without sending the security corpus to a hosted RAG provider.

The repository has two complementary parts:

1. Zagros Core — ingestion, HelixDB persistence, retrieval, CLI, MCP servers, and UI. Teams can run one instance on infrastructure they control and connect multiple MCP-compatible agent harnesses and internal tools to the same shared corpus.
2. Zagros Skills — independently authored agent guidance that teaches an AI agent how to investigate security questions, use Zagros evidence correctly, distinguish evidence from interpretation, and follow safe investigation practices.

Zagros favors authoritative upstream sources, explicit provenance, organizational control, and evidence-backed conclusions. Local single-user deployment remains supported, but the primary product model is a shared team service. The project is not tied to one agent harness, one model provider, or one deployment environment.

Current State (public pre-release baseline; example snapshot)

What is working right now

The counts below are a captured example baseline, not live website telemetry. Verify any running instance with zagros status or MCP index_status.

Example seeded corpus snapshot (captured 2026-09-08)

HelixDB URL  : http://localhost:47474
CVE nodes    : 499
  asvs        : 345
  attack      : 697
  capec       : 613
  cwe         : 969
  total       : 2,624 knowledge nodes

Verified live against this repository

The know command was run against patterns present in this codebase:

What is NOT yet implemented

Architecture

Current layer diagram

┌──────────────────────────────────────────────────────────────────┐
│                     AI Agent / LLM Client                        │
│           (OpenCode, Claude Desktop, VS Code, custom)            │
└─────────────────────────┬────────────────────────────────────────┘
                          │  Docker MCP Toolkit (stdio)
┌─────────────────────────▼────────────────────────────────────────┐
│                MCP Server (Rust / rmcp)                           │
│ search_cves  get_cve  index_status  sync_cves  search_knowledge  │
│ sync_knowledge_source  backfill_cves                              │
└──────┬──────────────────────────────────────────────────────────-┘
       │
┌──────▼──────────────────────────────────────────────────────────┐
│              BM25 Retrieval (in-process, lib.rs)                 │
│   rank_documents (Cve)    rank_knowledge (Knowledge)             │
└──────┬───────────────────────────────────────────────────────────┘
       │  HTTP  (helix-db crate → QueryRequest::read/write)
┌──────▼───────────────────────────────────────────────────────────┐
│                       HelixDB  :47474                            │
│  Cve nodes (499)    Knowledge nodes (2,624)                      │
│  No edges yet       No embeddings yet                            │
└──────────────────────────────────────────────────────────────────┘

Target layer diagram (full vision)

┌──────────────────────────────────────────────────────────────────┐
│                     AI Agent / LLM Client                        │
└─────────────────────────┬────────────────────────────────────────┘
                          │  Docker MCP Toolkit (stdio / SSE)
┌─────────────────────────▼────────────────────────────────────────┐
│                    MCP Server (Rust / rmcp)                       │
│  search_knowledge  analyze_code  check_config  get_finding       │
│  sync_knowledge_source  index_status  list_sources  explain_rule  │
└──────┬──────────────────┬──────────────────────┬─────────────────┘
       │                  │                       │
┌──────▼──────┐  ┌────────▼────────┐  ┌──────────▼──────────────┐
│  Retrieval  │  │ Deterministic   │  │  Evidence Assembler     │
│  BM25       │  │ Analyzer        │  │  + Confidence Scorer    │
│  + Vectors  │  │ (pattern rules, │  │  (citation chains,      │
│  + Graph    │  │  AST, OPA)      │  │   trust tiers)          │
└──────┬──────┘  └────────┬────────┘  └──────────┬──────────────┘
       │                  │                       │
┌──────▼──────────────────▼───────────────────────▼──────────────┐
│                      HelixDB                                     │
│  Graph edges   →  CWE / CAPEC / ATT&CK / ASVS relationships    │
│  Vector store  →  Semantic embeddings of standard chunks        │
│  Document store→  Chunks with full provenance envelopes         │
└─────────────────────────────────────────────────────────────────┘

Source Catalog

Tier 1 — Authoritative foundations

Tier 2 — Planned

Document Schema

Current: KnowledgeDoc (src/sources.rs)

pub struct KnowledgeDoc {
    pub id: String,          // e.g. "CWE-89", "ASVS-v5.0.0-1.2.5", "ATT&CK-T1190"
    pub name: String,        // short human-readable title
    pub description: String, // full text used for BM25 search
    pub source: String,      // "cwe" | "asvs" | "capec" | "attack"
    pub url: String,         // canonical source URL
    pub tags: String,        // tactic, platform, chapter, level, etc.
    pub provenance: Provenance, // publisher/version/URLs/license/timestamps/hash/trust tier
}

Current provenance envelope

{
  "publisher": "OWASP Foundation",
  "source_name": "OWASP ASVS",
  "source_version": "5.0.0",
  "canonical_url": "https://github.com/OWASP/ASVS/tree/v5.0.0",
  "retrieval_url": "https://raw.githubusercontent.com/OWASP/ASVS/v5.0.0/...",
  "license": "CC BY-SA 4.0",
  "retrieved_at": "2026-09-14T00:00:00Z",
  "upstream_updated_at": null,
  "content_sha256": "<64-hex SHA-256>",
  "trust_tier": "authoritative"
}

MCP Tools

Currently exposed

Target (Phase 3+)

Learning Path

Phase 1 — Foundations (COMPLETE)

Learning goal: understand the retrieval problem before adding AI complexity.

• Rust async HTTP with reqwest + tokio
• serde JSON serialization
• BM25 from scratch (IDF, TF, field weights, length normalization)
• CLI with clap, MCP server with rmcp
• HelixDB Docker sidecar, Docker MCP Toolkit integration

Key insight: RAG is retrieval first. Good retrieval without an LLM already provides value. An LLM on bad retrieval produces confident hallucinations.

Phase 2 — Structured Ingestion and Provenance (COMPLETE)

Learning goal: understand why provenance, versioning, and schema discipline matter from the start. Mistakes here cascade to every downstream component.

Done:

• Four authoritative sources parsed and stored in HelixDB: CWE, ASVS, CAPEC, ATT&CK
• Shared KnowledgeDoc type with structured Provenance
• Provenance stores publisher/source, source version, canonical/retrieval URLs, license, retrieval/upstream timestamps, SHA-256 content hash, and trust tier
• Source manifests record raw-source SHA-256 hashes; optional raw snapshots are preserved with ZAGROS_PRESERVE_RAW_SOURCES
• source <name|all> CLI command with progress reporting
• know <query> command for BM25 search over the knowledge corpus
• Idempotent upsert (safe to re-run any source ingestion)

Deferred source expansion:

• Add OWASP Cheat Sheets and other authoritative sources during Phase 3+

Key insight: A knowledge chunk without provenance is noise. You cannot trust a finding if you cannot explain which version of which standard produced it.

Phase 3 — HelixDB Graph + Vectors (NEXT)

Learning goal: understand when graph traversal outperforms vector similarity.

• Create CWE → ATT&CK technique edges using the official CWE/ATT&CK crosswalk
• Create CWE → ASVS requirement edges
• Generate embeddings for each chunk using a local or API-based model
• Store embeddings in HelixDB vector index
• Implement hybrid retrieval: BM25 + dense vectors + graph hops
• Fuse with Reciprocal Rank Fusion (RRF)
• Extend the current search_knowledge MCP capability with get_rule, explain_weakness, and map_to_attack

Key insight: “What controls address CWE-89?” is a graph traversal. “Find chunks about injection in user-supplied data” is a vector query. Combining both with RRF beats either alone.

Phase 4 — LLM Reasoning Layer

Learning goal: the correct role of an LLM — reasoning over retrieved evidence, never generating security claims from memory.

• LLM call that receives top-K cited chunks as structured context
• Structured output enforced with JSON schema validation in Rust
• Every LLM claim must include a cited evidence ID
• Quote anchoring: verify that an LLM-quoted phrase exists verbatim in the source
• analyze_code and check_config MCP tools

Key insight: the LLM explains and contextualizes findings that the retrieval system already found. It does not produce findings and it does not adjudicate compliance.

Phase 5 — Security Scanner Integration

Learning goal: build the evidence collection layer.

• AST-based code pattern extraction for Rust
• Kubernetes and Dockerfile manifest parser
• Terraform/HCL IaC parser
• SBOM generation and dependency lookup via OSV / GitHub Advisory Database
• Connect scan output to MCP tools

Phase 6 — Evaluation and Confidence Calibration

Learning goal: measure the system honestly and improve it systematically.

• OWASP Benchmark as evaluation harness
• Precision/recall per CWE/source
• Calibrate confidence scores against known-true findings
• Track false-positive rate as a first-class metric

Repository Layout

Current

zagros/
├── Cargo.toml                     # helix-db, quick-xml, csv, zip, rmcp, reqwest, …
├── Dockerfile                     # builds zagros-mcp image
├── docker/
│   ├── compose.yml                # HelixDB + MCP server stack
│   ├── zagros-server.yaml        # Docker MCP server registration
│   └── tools.json
├── src/
│   ├── lib.rs                     # Public API: ingest_*, rank_*, sync_*, backfill_*
│   ├── main.rs                    # CLI: ingest backfill source search know status
│   ├── db.rs                      # HelixDB client: Cve + Knowledge node CRUD
│   ├── sources.rs                 # KnowledgeDoc type + CWE/ASVS/CAPEC/ATT&CK parsers
│   └── bin/
│       ├── zagros-mcp.rs         # MCP stdio server
│       ├── zagros-mcp-http.rs    # MCP Streamable HTTP server
│       └── zagros-ui.rs          # Web UI/API
└── docs/
    ├── VISION.md                  # This document
    ├── README.md
    ├── CLI.md
    └── MCP.md

Target (Phase 3+)

The flat src/ layout will grow into subdirectories (ingestion/, retrieval/, analysis/, mcp/) as each phase introduces clearly bounded components. The current flat layout is intentional — it stays legible for learning without premature abstraction.

Design Constraints

Evidence before claims. No finding is reported without a retrieved chunk that directly supports it. Semantic resemblance alone is insufficient-evidence.

Version matching is a hard filter. A rule inapplicable to the artifact’s language, platform, or version is excluded before retrieval. This is a correctness requirement, not a performance hint.

Source identity is preserved. CIS, STIG, OWASP, and NIST controls that address the same concern are never merged into an unlabeled generic rule. Each finding traces to exactly one source and version.

Provenance is immutable. Raw downloads are stored as immutable snapshots with content hashes. Derived chunks reference the snapshot. Updates produce new records with new provenance; they do not overwrite old ones.

Scanned code is untrusted. Code comments, string literals, and documentation in scanned repositories must never reach the system prompt as instructions.

The LLM does not pass or fail. Compliance verdicts come from the rule engine or are marked manual-review. The LLM explains; it does not adjudicate.

License compliance is structural. Sources with redistribution restrictions store only rule IDs and metadata in the index. Full text is linked, not embedded.

Technology Stack

Non-Goals

• Does not produce CVSS scores.
• Does not automatically remediate findings.
• Does not replace Semgrep or CodeQL — it provides knowledge context for their output.
• Does not claim compliance certification for any standard.
• Is not a runtime intrusion detection system.

Success Criteria

Phase 2 (complete baseline)

• source all ingests all four Tier-1 sources without error and stores correct counts.
• know "SQL injection" returns CWE-89 and CAPEC-66 in the top three results.
• know "hardcoded credentials" returns ASVS-v5.0.0-V13.3.1 in the top five results.
• Provenance is attached to newly ingested CVE and knowledge records and exposed through MCP responses.
• Re-running any source command is idempotent (no duplicates).

Phase 3 (next milestone)

• know "what controls address SQL injection" traverses CWE-89 → ATT&CK T1190 → ASVS requirements via graph edges.
• Graph/vector results preserve the existing provenance envelope through retrieval.
• Retrieval evaluation expands to larger source-diverse corpora before scanner-level false-positive targets are introduced.

Full vision

• A query for “SQL injection in Rust” retrieves CWE-89, the relevant ASVS requirement, and the OWASP Injection Cheat Sheet within the top three results, each with exact source, version, and a supporting quotation.
• A submitted code snippet with a hardcoded credential is identified with a confirmed finding citing ASVS v5.0.0-2.10.1 and CWE-798.
• A Kubernetes manifest with securityContext.privileged: true is flagged citing Kubernetes Pod Security Standards Baseline.
• A finding without a retrieved evidence chain is returned as insufficient-evidence, never silently omitted or fabricated.