modelscan/verify

Open-source black-box model verification for OpenAI-compatible and Anthropic-compatible model gateways.

The verifier is designed to run as an independent service mounted under /verify on any host, for example https://example.com/verify. It can also run standalone without login or saved sites.

The repository is intended for the public modelscan/verify project. It contains the probe engine, minimal API, and web result UI. Probe templates and model fingerprint baseline data should live in modelscan/registry so public data stays in the registry repository.

License

• Code: AGPL-3.0-or-later.
• Probe templates and model fingerprint baseline data: CC BY-SA 4.0 in modelscan/registry.
• Contributions: DCO. Add Signed-off-by: Your Name <you@example.com> to commits.

What It Does

• Checks OpenAI-compatible /v1/chat/completions responses.
• Checks Anthropic-compatible /v1/messages responses.
• Runs behavior probes for instruction following, reasoning, code, safety, prompt injection, stability, and low-confidence self-identity signals.
• Produces a structured report with verdict, confidence score, risk signals, protocol evidence, usage evidence, and per-case details.

What It Does Not Do

• It does not authenticate users.
• It does not store API keys.
• It does not read or write a database.
• It does not provide SaaS history, scheduled rechecks, trend charts, or model-switch alerts.
• It does not prove model origin in a legal or cryptographic sense.
• It does not prevent a provider from adapting to public fixed probes.

Treat the result as evidence-based, probabilistic black-box verification. For high-stakes decisions, combine it with provider transparency logs, contractual evidence, official attestations, or controlled baseline comparisons.

Install For Development

python -m pip install -e '.[test]'
pytest -q

Python Usage

from model_verifier.report import run_verification
from model_verifier.types import VerificationOptions, VerificationTarget

report = run_verification(
    VerificationTarget(
        source="temporary",
        base_url="https://gateway.example.com",
        model="gpt-4.1",
        api_key="sk-...",
        api_key_masked="sk-...masked",
        site_name="Temporary gateway",
    ),
    VerificationOptions(
        claimed_model="gpt-4.1",
        provider_mode="auto",
        timeout_seconds=90,
    ),
)

print(report["verdict"], report["confidence_score"])

CLI Usage

model-verifier \
  --base-url https://gateway.example.com \
  --api-key "$API_KEY" \
  --model gpt-4.1 \
  --claimed-model gpt-4.1

Local Web UI

python -m pip install -e '.[test]'
model-verifier-demo --host 127.0.0.1 --port 7860

In another terminal:

cd apps/web
npm install
npm run dev -- --host 127.0.0.1 --port 5174 --strictPort

Open the /verify/ URL printed by Vite:

http://127.0.0.1:5174/verify/

The React page includes the locale switcher, login entry, temporary gateway verification, and optional saved-site verification. Temporary gateway verification works by default. When MODEL_VERIFIER_HOST_API_BASE_URL is set, the verifier service proxies host-owned login, saved sites, and saved models through HTTP:

• /verify/api/me
• /verify/api/sites
• /verify/api/models
• /verify/api/auth/*

The demo server also accepts the legacy unprefixed /api/* paths for local compatibility, but production should use /verify/api/*.

You can also start both local services with:

scripts/start.sh

By default this starts the verifier API on 127.0.0.1:7860, the Vite UI on 127.0.0.1:5174, and proxies host-owned login/site/model APIs to http://127.0.0.1:8000.

To run without a host API during local development:

MODEL_VERIFIER_HOST_API_BASE_URL= scripts/start.sh

Copy .env.example if you want to keep local overrides.

Deployment Shape

• Deploy this service separately from any host SaaS process.
• Configure your reverse proxy so /verify and /verify/* are served by this verifier service.
• Keep SaaS-only features, such as continuous verification, scheduled rechecks, history curves, and model-switch alerts, outside this open-source service unless you intend to open-source them too.
• Use HTTP APIs at the service boundary. Do not import verifier source code directly into the SaaS process.

The deploy script syncs this project to an SSH host and runs the verifier stack on a server-local port:

REMOTE=your-server \
PUBLIC_WEB_URL=https://example.com/verify \
scripts/deploy.sh

Useful overrides:

REMOTE=your-server \
DEPLOY_DIR=/opt/model-verifier \
APP_PORT=2004 \
PUBLIC_WEB_URL=https://example.com/verify \
MODEL_VERIFIER_HOST_API_BASE_URL=https://example.com \
MODEL_VERIFIER_HOST_API_INTERNAL_BASE_URL=http://host-api:8000 \
MODEL_VERIFIER_HOST_API_NETWORK=host_api_network \
scripts/deploy.sh

After deployment, add the generated ops/nginx-verify-location.conf location block to your HTTPS Nginx server so public /verify traffic is routed to the verifier service.

Private production deployments can keep their own SSH aliases, deployment directories, public URLs, and Docker network names outside the repository by passing environment overrides or using an untracked .env.production file.

Configuration

Variable	Purpose
PUBLIC_WEB_URL	Public /verify URL used for deployment output and operator checks.
MODEL_VERIFIER_HOST_API_BASE_URL	Optional public host API base URL for login redirects and host-owned APIs. Leave empty for standalone temporary verification.
MODEL_VERIFIER_HOST_API_INTERNAL_BASE_URL	Optional server-to-server host API URL used for proxied API calls.
MODEL_VERIFIER_HOST_API_NETWORK	Optional external Docker network that lets the verifier API reach the host API service by container name.
APP_PORT	Server-local port where the web container is exposed.

Production Notes

• Never log full API keys.
• Apply request timeouts and concurrency limits.
• Restrict outbound network access if exposing this as a public service.
• Keep temporary API keys in memory only.
• Consider rotating or randomizing probe sets in private deployments.