Inside Veylqorix

The system separates four layers: entry points (who runs a scan — terminal, agent, CI, browser), the integration layer (how they reach the engine — CLI, MCP, REST), the core engine (which scanner runs, when, and how results are normalized and gated), and the results & enforcement surfaces (reports, dashboards, and CI status checks). The core engine itself now has a byte-compatible Rust implementation ( crates/veylqorix-engine), reached through a TypeScript adapter that degrades honestly when the binary is missing.

System architecture — the diagram depicts the target design; the shipped implementation keeps the same engine/adapter separation in a pnpm TypeScript monorepo.

Scan lifecycle — normalize before judging, gate failures are first-class, verify don't trust.

The CLI is a thin adapter over the core engine: every result comes from a real scanner run, and a scanner that cannot run is reported as SKIPPED or ERROR, never as a clean pass. It is not published to npm yet — run it from the monorepo build.

veylqorix scan [root]                  full audit + quality gate
veylqorix check [root]                 quality checks only — no scanners run; always INCOMPLETE (exit 2)
veylqorix report [root]                Markdown report
veylqorix config validate FILE         validate a policy
veylqorix hooks install|uninstall      safe Git hooks

0   PASS         gate passed
1   FAIL         blocking findings
2   INCOMPLETE   coverage degraded — never green
64  usage error
65  bad root / missing policy
70  unexpected error

The MCP server exposes the engine to Claude Code, Codex, Cursor, and any MCP client. Inputs are Zod-validated; every response is structured, evidence-based, and redacted. The server only reads and scans — it has no write path.

{
  "mcpServers": {
    "veylqorix": {
      "command": "node",
      "args": ["/abs/path/packages/mcp-server/dist/bin.js"],
      "env": {
        "VEYLQORIX_ROOTS": "/abs/path/your/project",
        "VEYLQORIX_TIMEOUT_MS": "120000"
      }
    }
  }
}

A dependency-free REST API on port 4173 that registers repositories, runs real scans, and serves reports as JSON, Markdown, or SARIF. Every error is structured JSON; paths are validated against VEYLQORIX_ALLOWED_ROOTS when set; secrets are redacted in every response.

The API is loopback-only by default: it binds to 127.0.0.1. Set a non-loopback VEYLQORIX_API_HOST without VEYLQORIX_API_TOKEN and the server refuses to start. In protected/remote mode (a token set), every /api route except GET /api/health requires Authorization: Bearer <token> — a missing or malformed header is a 401, a wrong token a 403. CORS is an exact-origin allowlist from VEYLQORIX_CORS_ORIGINS; no wildcard, never credentialed. State (repositories and scans) is durable in a JSON store; on restart, in-flight RUNNING scans recover as INTERRUPTED — never completed, never lost, single-process.

Veylqorix reports what its scanners found. It does not certify the absence of vulnerabilities or secrets. Five things it is honest about, always: