Metadata-Version: 2.4
Name: vectimus
Version: 0.18.1
Summary: Stop your AI agents from breaking things. Intercepts every action and blocks the dangerous ones before they execute.
Author: Joseph Holland
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,cedar,governance,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Requires-Dist: cedarpy<5.0.0,>=4.8.0
Requires-Dist: click>=8.1.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: structlog>=24.0.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Provides-Extra: adk
Requires-Dist: google-adk>=1.0.0; extra == 'adk'
Provides-Extra: all
Requires-Dist: google-adk>=1.0.0; extra == 'all'
Requires-Dist: langchain>=0.3; extra == 'all'
Requires-Dist: langgraph>=0.2; extra == 'all'
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: langgraph
Requires-Dist: langchain>=0.3; extra == 'langgraph'
Requires-Dist: langgraph>=0.2; extra == 'langgraph'
Provides-Extra: server
Requires-Dist: fastapi>=0.115.0; extra == 'server'
Requires-Dist: uvicorn>=0.34.0; extra == 'server'
Description-Content-Type: text/markdown

# Vectimus

**Cedar policies for every AI agent action. Coding tools and agentic frameworks. Every evaluation under 5ms. Zero config.**

[![PyPI](https://img.shields.io/pypi/v/vectimus)](https://pypi.org/project/vectimus/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![CI](https://github.com/vectimus/vectimus/actions/workflows/ci.yml/badge.svg)](https://github.com/vectimus/vectimus/actions)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://pypi.org/project/vectimus/)

<p align="center">
  <img src="demo.gif" alt="Claude Code session with Vectimus blocking rm -rf, terraform destroy and force push while allowing safe commands" width="720">
</p>

## Install

```bash
pipx install vectimus
vectimus init
```

That's it. Cedar policies evaluate every tool call — whether from a coding agent in your terminal or a framework agent in production. Dangerous commands, secret access, infrastructure changes and supply chain attacks blocked before execution.

## Why this exists

AI coding agents and agentic frameworks run shell commands, write files, install packages and call APIs. Without a policy layer, nothing stands between a prompt injection and `rm -rf /`.

These are not hypothetical risks:

- **[Clinejection](https://snyk.io/blog/cline-supply-chain-attack-prompt-injection-github-actions/) (Feb 2026)** — A prompt injection in a GitHub issue title caused an AI agent to publish backdoored npm packages. 4,000 developer machines compromised in 8 hours.
- **[Terraform destroy incident](https://www.huuphan.com/2026/03/claude-code-wiped-production-database-terraform.html) (Feb 2026)** — An AI agent unpacked old Terraform configs and ran `terraform destroy`, wiping a production VPC, RDS database and ECS cluster.
- **[IDEsaster](https://thehackernews.com/2025/12/researchers-uncover-30-flaws-in-ai.html) (Dec 2025)** — Researchers found 30+ vulnerabilities across Cursor, Windsurf and GitHub Copilot. 24 CVEs assigned.

Vectimus is a defense-in-depth layer. Whatever permission setup your team uses, Vectimus adds deterministic policy evaluation underneath. Same input, same decision, every time.

## What it catches

Every policy references the real-world incident that motivated it. No "best practice" filler.

| Pack | What it blocks | Example |
|------|---------------|---------|
| **Destructive Ops** | `rm -rf`, `terraform destroy`, `docker system prune` | Production wipe prevention |
| **Secrets** | Credential file access, env variable exposure | `.env`, AWS keys, SSH keys |
| **Supply Chain** | `npm publish`, `pip install` from URLs, registry tampering | Clinejection-class attacks |
| **Infrastructure** | `terraform apply`, `kubectl delete`, cloud CLI mutations | Unreviewed infra changes |
| **Code Execution** | `eval()`, `exec()`, unsafe interpreter invocations | Code injection via agents |
| **Data Exfiltration** | `curl` to external hosts, file upload, data piping | Credential theft, data leakage |
| **File Integrity** | Writes to `.vectimus/`, sensitive config paths | Governance tampering |
| **Database** | Direct database CLI access, credential harvesting | Unauthorized data access |
| **Git Safety** | `git push --force`, history rewriting, credential commits | Repository damage |
| **MCP Safety** | Unapproved MCP servers, dangerous tool parameters | MCP server supply chain |
| **Agent Governance** | Unchecked agent spawning, goal hijacking, rogue agents | Multi-agent control |

11 packs. [Browse all policies →](https://vectimus.com/policies)

Maps to [OWASP Agentic Top 10](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/) (all 10 categories), SOC 2, NIST AI RMF, NIST CSF 2.0, ISO 27001 and EU AI Act. [Full compliance mappings →](https://vectimus.com/docs/compliance)

## Example policy

```cedar
@id("vectimus-supchain-001")
@description("Block npm publish to prevent supply-chain attacks")
@incident("Clinejection: malicious npm packages published by compromised AI agent, Feb 2026")
@controls("SLSA-L2, SOC2-CC6.8, NIST-AI-MG-3.2, EU-AI-15")
forbid (
    principal,
    action == Vectimus::Action::"package_operation",
    resource
) when {
    context.command like "*npm publish*"
};
```

Every rule has an `@incident` annotation linking it to the attack it prevents and `@controls` mapping it to compliance frameworks. Governance rules backed by real attacks are compelling. Rules that exist "because best practice" are not.

## Policies that stay current

Vectimus checks for policy updates in the background every 24 hours. New rules ship when new threats appear.

```bash
vectimus policy update    # Pull latest now
vectimus policy status    # Check version and sync info
```

Behind the scenes, [Sentinel](https://github.com/vectimus/sentinel) runs a three-agent pipeline daily:

- **Threat Hunter** scans the agentic AI security landscape for new incidents -- MCP vulnerabilities, tool poisoning, agent exploitation -- and classifies them against OWASP, NIST and CIS frameworks
- **Security Engineer** drafts Cedar policies and replays the incident in a sandbox to prove the policy catches the attack before opening a PR
- **Threat Analyst** writes the advisory and incident analysis for the [public threat feed](https://vectimus.com/threats)

A human reviews every PR. The policy ships. Your install picks it up automatically.

The entire pipeline is governed by Vectimus itself. The agents that write governance rules operate under the same governance system.

[Live threat dashboard →](https://vectimus.com/threats) | [Incident blog posts →](https://vectimus.com/blog)

## Works with

### Coding tools

| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | [Cursor](https://www.cursor.com/) | [GitHub Copilot](https://github.com/features/copilot) | [Gemini CLI](https://github.com/google-gemini/gemini-cli) |
|:-----------:|:------:|:--------------:|:----------:|
| ✅ | ✅ | ✅ | ✅ |

### Agent frameworks

| [LangGraph](https://github.com/langchain-ai/langgraph) | [Google ADK](https://github.com/google/adk-python) | [Claude Agent SDK](https://docs.anthropic.com/en/docs/agents) |
|:---------:|:----------:|:----------------:|
| ✅ | ✅ | ✅ |

Same Cedar policies govern both. One install.

<details>
<summary><strong>LangGraph / LangChain integration</strong></summary>

### Agent middleware

```python
from vectimus.integrations.langgraph import VectimusMiddleware

middleware = VectimusMiddleware(
    policy_dir="./policies",   # Optional, defaults to bundled policies
    observe_mode=False,        # Optional, defaults to False
)

agent = create_agent(
    model="openai:gpt-4.1",
    tools=my_tools,
    middleware=[middleware],
)
```

### MCP interceptor

```python
from vectimus.integrations.langgraph import create_interceptor

interceptor = create_interceptor(
    policy_dir="./policies",
    observe_mode=False,
)

client = MultiServerMCPClient(
    {...},
    tool_interceptors=[interceptor],
)
```

Both support observe mode for trialling without enforcement.

</details>

<details>
<summary><strong>Google ADK integration</strong></summary>

### Runner plugin (recommended)

```python
from vectimus.integrations.adk import VectimusADKPlugin

plugin = VectimusADKPlugin(
    policy_dir="./policies",   # Optional, defaults to bundled policies
    observe_mode=False,        # Optional, defaults to False
)

runner = Runner(
    agent=my_agent,
    app_name="my-app",
    session_service=session_service,
    plugins=[plugin],
)
```

### Per-agent callback

```python
from vectimus.integrations.adk import create_before_tool_callback

callback = create_before_tool_callback(
    policy_dir="./policies",
    observe_mode=False,
)

agent = LlmAgent(
    name="MyAgent",
    model="gemini-2.0-flash",
    before_tool_callback=callback,
)
```

</details>

## How it works

```
┌─────────────┐     ┌───────────────┐     ┌──────────────┐     ┌──────────┐
│  AI Agent   │────▶│   Vectimus    │────▶│ Cedar Policy │────▶│ allow /  │
│ (tool call) │     │  Normaliser   │     │   Engine     │     │ deny /   │
│             │◀────│               │◀────│              │◀────│ escalate │
└─────────────┘     └───────────────┘     └──────────────┘     └──────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │  Audit Log   │
                    │  (JSONL)     │
                    └──────────────┘
```

- **Normaliser** translates tool-specific payloads (Claude Code, Cursor, Copilot, Gemini CLI) into a unified Cedar request format
- **Cedar Engine** evaluates all loaded policies deterministically. No LLM in the loop. Same input, same decision.
- **Audit Log** records every decision with full context for compliance evidence and incident investigation

Evaluation is entirely local. Zero telemetry. The only network call is a background policy update check every 24 hours (disable with `vectimus policy auto-update off`). [Cedar](https://www.cedarpolicy.com/) is the same policy language used by [AWS AgentCore Policy](https://aws.amazon.com/bedrock/agentcore/) and [Amazon Verified Permissions](https://aws.amazon.com/verified-permissions/).

## MCP server governance

Vectimus blocks all MCP tool calls by default. During `vectimus init` it reads your existing tool configs and offers to approve the MCP servers you already use:

```
MCP servers detected:
  Claude Code:  posthog, slack
  Cursor:       github

Allow all 3 servers? [y/N]:
```

Manage the allowlist at any time:

```bash
vectimus mcp allow github
vectimus mcp allow slack
vectimus mcp list
```

Approved servers still go through input inspection rules that check for credential paths, CI/CD tampering and dangerous commands in tool parameters.

## Observe mode

Trial Vectimus without blocking anything. Observe mode logs all decisions but always allows actions.

```bash
vectimus observe on       # Log only, no enforcement
vectimus observe off      # Switch to enforcement
vectimus observe status   # Show current mode
```

Review the audit log at `~/.vectimus/logs/` to understand what your policies would block. Deploy in observe mode, review with your security team, then switch to enforcement.

## Per-project overrides

```bash
vectimus rule disable vectimus-destruct-003              # This project only
vectimus rule disable vectimus-destruct-003 --global     # All projects
vectimus rule overrides                                  # View overrides
```

Overrides live in `.vectimus/config.toml` in the project root. The `.vectimus/` directory is protected by policy -- agents cannot modify it.

## Server mode

For team-wide enforcement, run Vectimus as a shared server:

```bash
pip install vectimus[server]
vectimus serve
```

All agent hooks forward to the server for centralised policy evaluation, audit logging and identity-aware decisions. [Server documentation →](https://vectimus.com/docs/server)

## Uninstall

```bash
vectimus remove
```

Strips Vectimus hooks from all detected tools in the current project. Preserves non-Vectimus hooks. Config and audit logs at `~/.vectimus/` are not touched.

## Documentation

Full docs at [vectimus.com/docs](https://vectimus.com/docs):

- [Getting started](https://vectimus.com/docs/getting-started)
- [Writing policies](https://vectimus.com/docs/writing-policies)
- [Running a shared server](https://vectimus.com/docs/server)
- [Architecture](https://vectimus.com/docs/architecture)
- [Compliance mappings](https://vectimus.com/docs/compliance)

<details>
<summary><strong>Configuration reference</strong></summary>

Create `.vectimus/config.toml` in your project root:

```toml
[policies]
dir = "./policies"

[server]
host = "0.0.0.0"
port = 8420

[logging]
dir = "~/.vectimus/logs"

[mcp]
allowed_servers = ["github", "slack"]

[identity]
resolver = "git"
```

Or use environment variables:

| Variable | Purpose |
|----------|---------|
| `VECTIMUS_POLICY_DIR` | Policy directory path |
| `VECTIMUS_SERVER_URL` | Server URL for hook forwarding |
| `VECTIMUS_LOG_DIR` | Audit log directory |
| `VECTIMUS_OBSERVE` | Set to `true` for observe mode |
| `VECTIMUS_MCP_ALLOWED` | Comma-separated approved MCP servers |
| `VECTIMUS_API_KEY` | API key for server authentication |

</details>

## Contributing

Contributions welcome. Please open an issue before submitting large changes.

1. Fork and clone the repository
2. Install dev dependencies: `uv pip install -e ".[dev]"`
3. Run tests: `pytest`
4. Run linting: `ruff check src/ tests/`

## License

Apache 2.0. See [LICENSE](LICENSE).
