{"uid":"cap_qvhYjuLZ2FnylfvsUMmfb","slug":"vrsai-package-install-preflight-af33e5e0","name":"vrsai Package Install Preflight","description":"Check an exact npm or PyPI package version immediately before installation using current registry, vulnerability, malicious-package, withdrawal/deprecation, and verified provenance evidence. Returns ALLOW, REVIEW, BLOCK, or UNKNOWN with machine-readable reasons.","url":"https://api.vrsai.tech/v1/capabilities/package_install_preflight?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method","bodyType","body"],"properties":{"body":{"type":"object"},"type":{"type":"string","const":"http"},"method":{"enum":["POST"],"type":"string"},"bodyType":{"enum":["json","form-data","text"],"type":"string"}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object"}}}}},"responseSchema":{"type":"json","example":{"package":{"name":"@colors/colors","purl":"pkg:npm/%40colors/colors@1.5.0","version":"1.5.0","ecosystem":"npm"},"decision":"ALLOW","evidence":[{"source":"npm_registry","status":"OK","attempts":1,"latency_ms":120,"observed_at":"2026-08-26T00:00:00.000Z"},{"source":"osv","status":"OK","attempts":1,"latency_ms":240,"observed_at":"2026-08-26T00:00:00.000Z"},{"source":"deps_dev","status":"OK","attempts":1,"latency_ms":90,"observed_at":"2026-08-26T00:00:00.000Z"}],"unknowns":[],"observed_at":"2026-08-26T00:00:00.000Z","observations":{"deps_dev":{"licenses":["MIT"],"advisory_ids":[],"canonical_name":"@colors/colors","canonical_version":"1.5.0"},"registry":{"exists":true,"yanked":"NONE","integrity":"sha512-fixture-integrity","deprecated":false,"yanked_reasons":[],"install_scripts":[],"distribution_hashes":[],"repository_metadata":{"url":"https://github.com/Marak/colors.js","verified":false}},"provenance":{"verified":false,"attestation_types":[],"source_repositories":[],"expected_repository_match":"NOT_REQUESTED"},"vulnerabilities":{"families":[],"family_count":0,"max_severity":"NONE","raw_record_count":0,"malicious_package_signal":false},"evidence_complete":true},"reason_codes":["NO_BLOCKING_SIGNAL_OBSERVED"],"policy_version":"balanced-2026-08-26","input_fingerprint":"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.01/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_qnaENq0wTH2WuVJzg_k1P","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Checks an exact npm or PyPI package version against registry, vulnerability, malicious-package, withdrawal, and provenance signals immediately before installation, returning ALLOW, REVIEW, BLOCK, or UNKNOWN with machine-readable reason codes.","exampleAgentPrompt":"Before you install it, run a preflight safety check on npm package @colors/colors version 1.5.0 — I need to know if it's safe, withdrawn, or has any known vulnerabilities or malicious signals.","exampleUseCases":[{"title":"Block malicious npm package before install","prompt":"Before my CI pipeline installs lodash version 4.17.20 from npm, check whether it's safe — flag it if there are any malicious signals, vulnerabilities, or provenance issues."},{"title":"PyPI dependency safety gate for AI agent","prompt":"I'm about to add requests version 2.28.0 from PyPI to my project — can you run a preflight check to confirm it's not withdrawn, vulnerable, or tampered with before I lock it into requirements.txt?"},{"title":"Supply chain audit for unknown package","prompt":"We found @colors/colors@1.5.0 in a vendor's code and need to know if it's safe to allow in our environment — check it against registry status, known vulnerabilities, and provenance attestation right now."}],"resultDescription":"Returns a JSON object with a top-level decision field (ALLOW, REVIEW, BLOCK, or UNKNOWN), an array of reason_codes explaining the decision, a package object with name/version/ecosystem/purl, and a detailed observations section covering registry status (existence, yanked/deprecated, integrity, install scripts), vulnerability families and max severity, malicious package signals, provenance attestation details, and license information. Each evidence source (npm registry, OSV, deps.dev) is listed with latency, attempt count, and observed timestamp. An unknowns array lists any evidence gaps.","failureModes":["Package not found in registry — may return UNKNOWN with reason code indicating absence","Network timeout to upstream registry or vulnerability database — evidence source marked with error status","Unsupported ecosystem — only npm and PyPI are supported; other ecosystems may return UNKNOWN","Invalid purl or version format — request rejected with validation error","Upstream OSV or deps.dev unavailable — partial evidence returned with unknowns populated","Ambiguous version specifier (range instead of exact) — may reject or return UNKNOWN"],"whenToPreferThis":"Use this endpoint when you need a real-time, pre-installation safety gate for an exact npm or PyPI package version — particularly in automated CI/CD pipelines, agent-driven dependency resolution, or any workflow where installing a compromised or vulnerable package would have downstream consequences. It is preferable to static lock-file scanners when the package version is determined dynamically at runtime, or when you need fresh registry and vulnerability data at the moment of install rather than at audit time. Choose it over generic vulnerability databases when you need a single authoritative ALLOW/REVIEW/BLOCK decision that combines registry status, OSV vulnerabilities, malicious-package signals, and provenance attestation in one call.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-13T06:44:06.723Z","isFirstParty":false,"canonicalSlug":"vrsai-package-install-preflight-af33e5e0"}