From first check to
enforced policy.

START HERE

What ossfind does

ossfind is a dependency decision service for AI-assisted development. It checks a direct package at an exact version against an administrator-controlled license and vulnerability policy before adoption, then records who requested the decision, which policy was applied, and which evidence was available.

QUICK START

Install an authorized customer build

ossfind 0.3.0 is delivered by Pamyn under commercial terms. Use Node.js 24.20 or later. Verify the package checksum supplied with your order, then install the archive in an administrator-managed location.

mkdir ossfind-install && cd ossfind-install
npm install /secure/path/ossfind-0.3.0.tgz
./node_modules/.bin/ossfind --version

Connect to the central service

Ask your administrator for the HTTPS service origin and an evaluator token. Store the token in your approved secret manager. Do not put it in a command argument, repository file, MCP JSON or TOML.

On the public Pamyn demo, developers can request a 24-hour evaluator day pass in the console. The first key is automatic while the shared five-per-day quota remains available; it permits ten evaluations. Save the one-time key ID and renewal secret securely. Another day requires an administrator-approved renewal, which the developer redeems in the console. Customer pilots use operator-issued credentials instead.

export OSSFIND_API_URL=https://your-ossfind-service.example
export OSSFIND_API_TOKEN=your-evaluator-token
./node_modules/.bin/ossfind evaluate express --package-version 5.1.0 --json

Exit 0 means a live allow decision was recorded. Exit 2 means review, deny or demo evidence. Exit 1 means input, configuration, network, authentication or storage failure.

CORE CONCEPTS

How to read a decision

A decision is tied to the package coordinate, exact version, evidence retrieval time and policy fingerprint. It is not a guarantee that the package is vulnerability-free, compatible, legally suitable or safe at runtime.

CLI REFERENCE

Commands

ossfind search "HTTP client" --ecosystem npm --limit 5
ossfind inspect axios --json
ossfind detect . --json
ossfind evaluate Pillow --ecosystem pypi --package-version 12.1.0 --json
ossfind gate --base "$BASE_SHA" --head "$HEAD_SHA" --mode observe --format github

Use --help for the installed build’s full argument list. Machine consumers should use --json and must still enforce the exit code.

CODING AGENTS

Connect through MCP

The installed ossfind-mcp process is a local stdio bridge. It is agent-independent and can be launched by GitHub Copilot in VS Code, Claude Code, Codex and other MCP clients. The central HTTP service is not a remote MCP endpoint.

ossfind setup copilot
ossfind setup claude
ossfind setup codex

1. Run the matching setup command from the final installation path.
2. Merge the printed entry into the client’s existing configuration.
3. Expose OSSFIND_API_URL and OSSFIND_API_TOKEN to the client-launched process through approved secret handling.
4. Restart or reload the client, list tools, and test one known allow and one known deny.

Available MCP tools

PULL REQUEST CONTROL

Protect dependency changes in GitHub

The gate compares committed Git objects, finds the merge base, extracts supported changed direct dependencies and sends exact versions to the same central evaluator. It does not run repository code or invoke a package manager.

OSSFIND_API_URL=https://your-ossfind-service.example \
OSSFIND_API_TOKEN="$TOKEN" \
ossfind gate --base "$BASE_SHA" --head "$HEAD_SHA" --mode observe --format github

Start in observe: review/deny/unresolved findings are reported while the gate exits 0, but setup and service failures exit 1. After policy tuning, use block and require the check in branch protection. Block mode exits 2 for review, deny or unresolved findings. The current maximum is 25 changed exact versions per run.

Changed pnpm, Yarn, Bun, Poetry, uv and Gradle dependency files are reported as unresolved. Fork pull requests normally do not receive repository secrets. Use your organization’s trusted-run process.

HTTP API

Central service interface

All API calls use Authorization: Bearer <token>. Health endpoints are public. Give every repository or agent installation its own least-privilege service principal.

curl --fail-with-body https://your-ossfind-service.example/api/v1/evaluations \
  -H "Authorization: Bearer $OSSFIND_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"ecosystem":"npm","name":"express","version":"5.1.0"}'

Status 400/415 means invalid input, 401 invalid credentials, 403 insufficient role or disallowed origin, 404 unavailable endpoint, 408/413 slow or oversized body, 429 quota exceeded, and 503 unexpected service or storage failure. Every non-2xx response means no approval.

POLICY

Configure organizational rules

A policy can allow exact registry license strings, block advisory severities, and deny named components. Unknown keys are rejected. Changes are loaded at startup and every decision includes the canonical SHA-256 policy fingerprint.

{
  "id": "engineering-default-v1",
  "allowedLicenses": ["MIT", "Apache-2.0", "BSD-3-Clause"],
  "blockedSeverities": ["critical", "high"],
  "deniedComponents": ["npm:example-blocked-package"]
}

License matching is exact string policy, not legal compatibility analysis. For example, MIT OR Apache-2.0 does not equal MIT. Unknown or ambiguous advisory severity requires review. A known deny takes precedence. Policy changes require a service restart; 0.3.0 has no policy-write or exception-approval API.

OPERATIONS

Run a single-organization instance

Use TLS ingress, network access controls, a persistent local volume for SQLite, and a unique evaluator credential per integration. Set OSSFIND_PUBLIC_ORIGIN to the exact HTTPS origin. Do not run multiple replicas against the same SQLite file.

Default service limits

• Four concurrent API operations and 60 authenticated requests per minute for each discovery and governance workload bucket, per process.
• Thirty evaluations and five uncached AI review briefs per principal per minute.
• 16 KiB JSON request bodies and a 10-second body deadline.
• Shorter caching for security evidence; expired evidence never becomes a fallback approval.

Optional Gemini review briefs

AI is off by default. To enable it, use a paid Gemini API project approved for the customer data involved, keep the key in server-side secret storage, and set all three variables below. Pin the model instead of accepting silent model changes.

OSSFIND_REVIEW_AI=gemini
GEMINI_API_KEY=<secret manager reference>
OSSFIND_GEMINI_MODEL=gemini-3.8-flash
OSSFIND_GEMINI_DATA_TERMS=paid-approved
OSSFIND_REVIEW_BRIEFS_PER_PRINCIPAL_PER_MINUTE=5

Each uncached request uses the Gemini Interactions API with provider storage disabled, no tools, bounded response size and strict structured-output validation. OSSFIND_GEMINI_DATA_TERMS=paid-approved is a startup acknowledgement that the project is on paid terms and approved for the submitted evidence. Valid briefs are cached in the audit database by decision, audience, provider, model and prompt version. Every provider disclosure records the requesting principal in a separate audit log. Provider failure leaves the recorded outcome unchanged.

Monitor /api/usage for supplier requests, cache hits and misses, upstream 429 responses, the latest reported rate-limit headroom, results by ecosystem and search latency. When AI review is enabled, it also reports aggregate provider calls, successes, cache/coalescing counts, errors and token usage. Metrics are in-memory and reset when the process restarts; they are operational signals, not billing records.

Backup and upgrade

1. Stop the service and close database connections.
2. Copy the entire data directory, including SQLite WAL files if present.
3. Restore to a separate instance and verify history before relying on the backup.
4. Pin the authorized release, upgrade while stopped, then verify readiness, one authenticated evaluation and history retrieval.

Rotate credentials by adding a new SHA-256 token digest under a unique principal, distributing the new secret, restarting, then removing the old principal and restarting again. Never remove the last administrator.

SECURITY AND DATA

Know what leaves your environment

An exact evaluation sends the ecosystem, package name and version to its public metadata provider and OSV. It does not require repository source. Package coordinates can still reveal technology choices and should follow your data-classification rules. Discovery can contact additional registries and metadata services.

Credentials are stored as cryptographic hashes in service configuration. Decision history stores the authenticated principal ID, package coordinate, outcome, reasons, evidence summaries, timestamps and policy fingerprint. Restrict ingress logs so authorization headers are never recorded.

Optional Gemini review sends a minimized projection of a selected review/deny decision: package coordinate, outcome, reason codes, license and evidence status, advisory IDs/severity, scope and requested audience. It does not send source code, audit actor, credential or freeform customer prompt. Review Google’s paid-service terms and DPA for each deployment.

Remote aggregate telemetry is disabled unless an operator explicitly enables both its switch and HTTPS endpoint. It excludes queries, package names, paths, credentials and governance evidence. Review the security overview and privacy information before a pilot.

TROUBLESHOOTING

Common failures

PRODUCT SCOPE

Current boundary

LICENSE AND SUPPORT

Commercial access

ossfind 0.3.0 and later are proprietary Pamyn software. An accepted proposal, order or written commercial agreement controls access, permitted deployment, integrations, updates and support. There is no public 0.3.0 source archive.

Versions through 0.1.12 remain available to their recipients under MIT. The already exposed 0.2.0 snapshot remains available to its recipients under AGPL-3.0-only; their existing rights are unchanged. Those historical rights do not grant access to 0.3.0 or later.

Documentation updated September 12, 2026 · Applies to ossfind 0.3.0