proov

Detect, analyze, and report AI execution artifacts on a host machine.

proov is a Rust CLI tool that scans your system for AI-related configuration files — things like .cursorrules, MCP server configs, prompt files, and container definitions — analyzes them for risk, and produces structured reports.

Support Proov

If Proov helps your team, you can support ongoing open source development with a donation via Stripe:

Donate to Proov

How it works

proov is local-first. It walks your filesystem, identifies AI execution artifacts, scores them for risk, and writes results locally. Network activity only happens when you explicitly opt into submission-related flows or proov update. proov auth and proov setup only save local configuration.

If you want a hosted review, policy, and governance surface, proov can submit to compatible ingest APIs. You can configure an endpoint during setup or pass one directly at submission time.

System requirements

Requirement	Detail
OS	macOS (ARM64, x86_64), Linux (ARM64, x86_64), Windows (x86_64)
Runtime	None — official releases are single binaries with no sidecar service
Build	Rust 1.85.1+ (pinned via rust-toolchain.toml)
Network	Optional — only needed for submission-related flows and self-update
Disk	~15-25 MB for the binary depending on platform; reports are only written when requested

Install

Homebrew (recommended on macOS)

brew tap AgenticHighway/tap
brew install proov
proov quick

Homebrew is the smoothest install path on macOS while direct-download artifacts are not yet signed and notarized.

From a release binary

Download the latest binary for your platform from GitHub Releases.

# macOS (Apple Silicon)
tar xzf proov-darwin-arm64.tar.gz
./proov quick

# Linux (x86_64)
tar xzf proov-linux-amd64.tar.gz
./proov quick

Verifying downloads

Each GitHub Release includes checksums.txt (SHA-256 hashes for all release assets) and checksums.txt.sig (a KMS ECDSA signature over checksums.txt, using the same key that proov update trusts).

# Download the binary and checksums for your platform, then:

# Linux — verify SHA-256
sha256sum --check --ignore-missing checksums.txt

# macOS — verify SHA-256
shasum -a 256 --check --ignore-missing checksums.txt

For the full signature-verification procedure (including how to verify checksums.txt.sig with the embedded public key), see docs/release-verification.md.

From source

git clone https://github.com/AgenticHighway/proov.git
cd proov
cargo build --release
./target/release/proov quick

Quick start

proov                      # Interactive wizard — walks you through options
proov quick                # Fast scan of AI config areas (~/.cursor, VS Code, Claude, etc.)
proov scan                 # Default scan (home directory, recursive)
proov full                 # Deep system-wide scan (slow, thorough)
proov file <path>          # Scan a single file
proov folder <path>        # Scan a directory
proov repo <path>          # Deep-scan a git repository
proov setup                # Interactive connected-mode setup (API key + endpoint)
proov auth                 # Prompt securely for an API key and save it
proov auth --key <key>     # Save API credentials directly (useful for automation)
proov update               # Check for and install updates
proov rules list           # List installed custom detection rules
proov rules add <file>     # Install a TOML rule file
proov rules remove <name>  # Remove an installed rule by name
proov rules validate <f>   # Validate a rule file without installing

Output formats

proov quick              # Overview with risk bars (default)
proov quick --full       # Detailed per-artifact breakdown
proov quick --summary    # Compact statistics only
proov quick --json       # JSON report to stdout
proov quick --out        # JSON report to ./proov-report.json
proov quick --out r.json # JSON report to a custom path
proov quick --contract   # Scanner data contract JSON to stdout
proov quick --contract --out r.json  # Contract JSON to file
proov quick --contract --submit --api-key <key>  # Contract to file + submit

--json, --out, and --contract all emit the scanner data contract shape used for compatible ingest APIs and local automation.

What it detects

The table below is representative, not exhaustive. proov combines built-in detectors, packaged TOML rules, and optional custom rules, so additional file names and patterns may be detected beyond these common examples. For deeper detector details, see docs/detectors.md.

Detector	Files	What it looks for
Cursor / editor rules	.cursorrules, agents.md, AGENTS.md	AI instruction files with capability keywords (TOML rule)
Prompt configs	*.prompt.md, *.instructions.md, copilot-instructions.md	Prompt configuration for GitHub Copilot and similar (TOML rule)
MCP configs	mcp.json, claude_desktop_config.json	Model Context Protocol server declarations
Container configs	Dockerfile, compose.yaml, docker-compose.yml	Docker image definitions and service orchestration with direct AI evidence or nearby agent artifacts
Browser footprints	Chrome, Edge, Brave, Arc profiles	Extension directory presence only (no content reads)
Custom rules	Any .toml in ~/.ahscan/rules/	Declarative rules you define

Risk scoring

Every artifact gets a risk score from 0–100:

Score	Severity	Color	Meaning
90+	CRITICAL	Magenta	Credential exposure or extreme risk
70-89	HIGH	Red	Dangerous capability combinations
40-69	MEDIUM	Yellow	Notable capabilities worth reviewing
10-39	LOW	Cyan	Minor signals, likely benign
0-9	INFO	Dim	Informational only

Scores are based on: artifact type, detected capability keywords (shell, network, filesystem, etc.), dangerous keywords (exfiltrate, steal, bypass, etc.), and whether capabilities are explicitly declared.

Optional local access mode

By default, proov shows the full local report.

If you want to locally limit emitted findings to the top three visible artifacts, add an .ahscan.toml file in your project root:

[access]
mode = "lite"

When .ahscan.toml is absent, proov keeps full output enabled.

Submitting to a compatible endpoint

proov supports hosted submission flows through compatible ingest APIs. You can configure an endpoint during setup or pass one directly for self-hosting, testing, or interoperability.

With an API key configured:

# First-time setup (saves credentials and endpoint)
proov setup

# Or prompt securely for credentials
proov auth

# Or set credentials directly for automation
proov auth --key your-api-key

# Submit scan results (uses saved endpoint)
proov repo . --submit --api-key your-key

# Submit to a custom public endpoint — requires --allow-public-endpoint
proov repo . --submit https://example.com/api/scans/ingest \
  --allow-public-endpoint --api-key your-key

# Save a custom public endpoint for future use — also requires the flag
proov auth --key your-api-key \
  --endpoint https://example.com/api/scans/ingest \
  --allow-public-endpoint

What is included in a submission

Each submission payload contains:

• Scan root paths — the filesystem paths where the scan ran (e.g. /Users/you)
• Machine hostname — the host's reported hostname
• AI artifact metadata — file paths, content hashes, capability signals, and risk scores for detected artifacts
• MCP server config metadata — server commands, tool names, and env-var names (values are never transmitted)
• Host security context — macOS firewall state on macOS; empty on other platforms
• Scanner metadata — version, OS, and architecture

No file contents, secret values, or credential material are transmitted.

In interactive flows (proov scan / proov quick / etc. from a terminal), proov displays this summary and asks for confirmation before sending.

In automation flows (--submit --api-key …), the submission proceeds without a prompt. Review the data categories above before embedding proov in CI/CD pipelines.

--allow-public-endpoint

By default, proov blocks submission to public (non-localhost, non-private-network) endpoints at the flag level. This prevents accidental data exfiltration in scripts that omit an explicit endpoint. Pass --allow-public-endpoint when you intentionally want to submit to or save a public endpoint.

Local endpoints (localhost, 127.0.0.1, ::1, RFC-1918 addresses) are always allowed without the flag.

Safety defaults

• Scans stay local unless you explicitly opt into connected commands
• Compatible submission endpoints are supported, whether configured ahead of time or passed on the command line
• Contract sync only runs during explicit submission flows, when the target endpoint exposes a compatible contract API
• Retry logic handles transient failures (429, 502, 503, 504)
• On Unix-like systems, saved API keys are written to ~/.config/ahscan/config.json and proov explicitly tightens directory/file permissions to 0700 / 0600
• On Windows, saved API keys are written under the current user's config directory, typically %APPDATA%\\ahscan\\config.json, and currently rely on the default per-user profile ACLs rather than explicit ACL hardening by proov

Self-update

proov update           # Check for and install updates
proov update --check   # Check only, don't install
proov update --force   # Force update even if current

proov update explicitly checks for the latest release, verifies the signed manifest, checks the matching artifact SHA-256, and replaces the local binary.

Official release binaries verify a detached AWS KMS-backed ECDSA signature on the update manifest before trusting artifact URLs or hashes.

Source builds remain fully functional, but proov update will fail explicitly unless the binary was built with PROOV_UPDATE_PUBLIC_KEY_DER_B64 set at compile time.

Privacy

• Path-first scanning — content is only read from specific allowlisted file types
• Bounded walking — max depth of 5 for shallow scans; full scan enumerates the entire filesystem with no caps
• Scoped exclusions — .git/, node_modules/, .venv/, target/ and similar are excluded from home/workdir/filesystem scans (full scan has no exclusions)
• Secret detection without storage — token patterns trigger a signal tag, but values are never stored or transmitted
• Browser presence only — extension directories are noted, but no extension content or preferences are read
• Declarative rules — custom rules are TOML config files; they use the same content-read allowlist as built-in detectors

Project structure

proov/
├── crates/
│   └── proov/                    # CLI binary (scanning, detection, submission)
│       └── src/
│           ├── detectors/         # Built-in artifact detectors
│           └── contract/          # Scanner data contract builders
├── rules/                        # Built-in TOML detection rules (compiled into binary)
├── examples/
│   └── rules/                    # Example custom detection rules (.toml)
├── scripts/
│   ├── test-scanner.sh           # Automated test suite
│   └── test-submit.sh            # Manual submission test
├── docs/
│   ├── architecture.md           # System design and data flow
│   ├── user-flows.md             # Public CLI journeys and UX paths
│   ├── detectors.md              # How detection works
│   ├── output-spec.md            # Plain-English spec for contract outputs
│   └── custom-rules.md           # Writing custom detection rules
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                # PR checks: fmt, clippy, test, audit
│   │   └── release.yml           # Build + GitHub Release + artifact publishing
│   ├── dependabot.yml            # Automated dependency updates
│   └── CODEOWNERS                # Required reviewers for security-sensitive files
├── CODE_OF_CONDUCT.md            # Community expectations and reporting path
├── LICENSE                       # AGPL-3.0-only license text
├── agents.md                     # Project guidelines for AI coding agents
├── deny.toml                     # Supply chain policy (licenses, advisories)
├── rust-toolchain.toml           # Pinned Rust compiler version
├── SECURITY.md                   # Vulnerability disclosure policy
└── scanner-data-contract.json    # JSON Schema for scan output

Developing

cargo build                         # Debug build
cargo fmt --check                   # Formatting check
cargo clippy --all-targets -- -D warnings  # Lint (must be 0 warnings)
cargo test                          # Run the full test suite
cargo deny check                    # License + advisory audit
cargo audit                         # RustSec vulnerability scan
./scripts/test-scanner.sh           # Exercise all CLI subcommands

CI runs all of these automatically on every PR. See .github/workflows/ci.yml for the full pipeline.

For detailed development instructions: CONTRIBUTING.md For architecture and code walkthrough: docs/architecture.md For public CLI journeys: docs/user-flows.md For the plain-English output spec: docs/output-spec.md For community expectations: CODE_OF_CONDUCT.md For security vulnerability reports: SECURITY.md

Configuration reference

File	Purpose
~/.config/ahscan/config.json	API key + endpoint (created by proov setup)
.ahscan.toml	Optional local access-mode settings
~/.ahscan/scanner_uuid	Persistent scanner identity (auto-generated)
~/.ahscan/rules/*.toml	Custom detection rules

Optional .ahscan.toml:

[access]
mode = "lite"                   # limit visible findings to the top three artifacts

License

Copyright (C) 2026 Agentic Highway.

proov is licensed under AGPL-3.0-only. See LICENSE and COPYRIGHT.