Vexqr Core (Python)

AI-Supervised Cybersecurity Tool Orchestration Platform — Python core.

A pipeline that connects any AI client (Claude, Gemini, Copilot, GitLab Duo, Cursor, Codex, custom OpenAI-compatible) to security tools — via MCP servers when available, or via terminal automation as a fallback — and supervises the worker AI in real time so it does not loop, waste tokens, or wander.

The core is Python. It is supported by:

• TypeScript adapters for MCP / IDE clients (see the repository root).
• C and hand-tuned Assembly accelerators for hot paths (token estimation, fuzzy-signature hashing) — see src/vexqr/accel.
• A Java performance layer (JDK 21+) for high-throughput, cross-platform fan-out (parallel tool dispatch, concurrent sub-agent monitoring) — see src/vexqr/perf.

Everything degrades gracefully: with no native components installed the platform runs in pure Python with identical behavior, just slower on the hot paths.

The security layer (scope enforcement, risk gating, audit logging) is owned and implemented separately by the security team. It is intentionally not part of this package.

Install

pip install .                 # pure-Python core (zero native build steps)
pip install '.[accel]'        # + C/Assembly fast paths and the Java bridge
pip install '.[mcp]'          # + official Model Context Protocol SDK
pip install '.[dev]'          # + test dependencies

Optional: build the native accelerator

cd src/vexqr/accel && make            # C + hand-tuned x86-64 Assembly
# or, portable C only (any architecture):
cd src/vexqr/accel && make portable

Optional: build the Java performance layer (JDK 21+)

cd src/vexqr/perf
javac -d out java/com/vexqr/perf/DispatchCoordinator.java
jar --create --file vexqr-perf.jar -C out .

Usage

# Run a supervised assessment (simulated, safe, no tools installed/executed)
vexqr run "check if my web app is secure" --target scanme.nmap.org --dry-run

# Emit machine-readable JSON
vexqr run "full security assessment" --target example.test --dry-run --json

# Inspect run history and export the audit trail
vexqr history
vexqr export <task_id>

# Registry + native acceleration status
vexqr registry
vexqr accel

Programmatic:

import asyncio
from vexqr import Vexqr
from vexqr.platform import VexqrOptions
from vexqr.core.store import SessionStore

async def main():
    store = SessionStore()                       # persists to .vexqr/sessions.db
    app = Vexqr(VexqrOptions(client="custom", dry_run=True, store=store))
    result = await app.run("check if my web app is secure", "scanme.nmap.org")
    print(result.summary)

asyncio.run(main())

Architecture

Five vertical layers plus a cross-cutting supervisor:

Cross-cutting: core/ (types, config, events, reporter, SQLite session/audit store), util/ (IDs, ANSI, logging, native acceleration bridge).

Test

pip install '.[dev]'
pytest                # src/ is on the path via pyproject [tool.pytest.ini_options]