nulvec 0.1.0

Perceptual AI security — scan images, PDFs, and web content for adversarial injections

Nulvec

Nulvec is a local-first security scanner for agent inputs.

It scans files and repositories for high-signal attack patterns before they reach an LLM or agent runtime:

• SKILL.md supply-chain attacks
• prompt injection in MCP payloads and code comments
• credential exfiltration patterns
• hidden PDF and image payloads
• image scaling and steganography attacks

Install

pip install nulvec

For image scanning, install Tesseract on the host:

brew install tesseract

Quick Start

nulvec scan suspicious-skill.md
nulvec scan . --block-on critical
nulvec install
nulvec skill install ./skills/my-skill
nulvec mcp-proxy -- python my_server.py
nulvec logs
nulvec config show
nulvec status
nulvec doctor

Python API

import nulvec

result = nulvec.scan("document.pdf")
print(result.decision)

Machine-Level Install

nulvec install creates a local policy file, event log, and Git protection layer. It installs a Git shim earlier in PATH, configures Git template hooks for future clones, and adds managed hooks to the current repository when run inside one.

Current support matrix:

• Git clone scanning via temp clone + pre-finalize repo scan
• Git pull scanning for simple git pull flows via fetch + temp worktree scan
• Git post-checkout/post-merge hooks as a fallback repo scan layer
• Skill install protection via nulvec skill install <path-or-url>
• Approved skill artifact hash cache under the local Nulvec runtime
• Stdio MCP proxy via nulvec mcp-proxy -- <server command>
• Local audit events via nulvec logs
• Local policy inspection via nulvec config show

Skill Protection Boundary

Nulvec does not automatically intercept arbitrary third-party skill installers.

The protected v1 path is:

nulvec skill install <path-or-url>

If you install a skill through some other CLI, Nulvec does not own that execution path and cannot honestly claim automatic pre-install protection there.

MCP Proxy Setup

The MCP proxy is manual in v1. You must point the supported client or server launch command at:

nulvec mcp-proxy -- <real server command>

This is the right current story for local developer tools such as Codex CLI, Claude Code, and OpenCode: configure each MCP server entry to launch through the proxy so Nulvec can scan server responses before they reach the client.

Codex CLI Example

Codex CLI supports MCP server configuration in TOML via:

• global config: ~/.codex/config.toml
• per-project config: .codex/config.toml for trusted projects

Example stdio wrapper configuration:

[mcp_servers.context7]
command = "nulvec"
args = ["mcp-proxy", "--", "npx", "-y", "@upstash/context7-mcp"]

Notes:

• Codex uses an argv model, not a shell snippet, so wrapper commands must be tokenized correctly.
• In controlled environments, MCP allowlist or identity rules may need to be updated when the command changes from the original server launcher to nulvec.

Claude Code Example

Claude Code supports stdio MCP servers through JSON config or the claude mcp CLI.

Common MCP config locations:

• user/local scope MCP servers: ~/.claude.json
• project scope MCP servers: .mcp.json

Example project config:

{
  "mcpServers": {
    "airtable": {
      "type": "stdio",
      "command": "nulvec",
      "args": ["mcp-proxy", "--", "npx", "-y", "airtable-mcp-server"],
      "env": {}
    }
  }
}

Equivalent CLI shape:

claude mcp add --transport stdio airtable -- nulvec mcp-proxy -- npx -y airtable-mcp-server

Notes:

• Claude CLI flag ordering matters. Claude flags must come before the server name, and the wrapped server command must come after --.
• MCP scope storage is separate from general Claude settings. Do not assume MCP local scope lives under .claude/settings.local.json.
• In managed environments, exact command-array allowlists can block wrapped commands unless the allowlist is updated for the new nulvec launcher.

OpenCode Example

OpenCode stores MCP servers in JSON config and uses a command-array model for local servers.

Common config locations:

• global config: ~/.config/opencode/opencode.json
• project config: opencode.json

Example local MCP config:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "server-everything": {
      "type": "local",
      "command": ["nulvec", "mcp-proxy", "--", "npx", "-y", "@modelcontextprotocol/server-everything"],
      "enabled": true
    }
  }
}

Notes:

• OpenCode’s local MCP command is already an argv array, which makes wrapper insertion straightforward.
• If you later automate rewiring, be careful with config-path detection for .json, .jsonc, and older install-path variants documented by OpenCode.