Scan results and agent access

Read the result

npx vibebeacon@latest scan --upload --json

The upload result includes a versioned report with new, resolved, reopened and remaining alert counts. Each changed alert has its ID, advisory ID, package and reason. A resolved status describes inventory matching; inspect the reason before calling it a fix.

• Unchanged scan: inventory refreshed, no alert transitions. Advisory updates can still change findings.
• Changed version: the uploaded version no longer matches. Check all installed copies, test the change and verify deployment separately.
• Omitted package: removal or reduced coverage, never a verified fix. Keep the same app identity and scan scope when comparing. Using --no-dev or --single reduces coverage.
• Reopened: a previously resolved alert qualifies again in the new inventory.
• Pending: inventory was accepted, but matching or scoring is incomplete, failed, or was superseded. Counts and score after may be null; do not read null as zero.
• No previous scan: baseline is unavailable. There is no supported before/after comparison. Workspace counts can reveal some scope changes, but equal counts do not prove identical coverage.

Read-only access for agents

npx vibebeacon@latest findings --name "My app" --json

This reads the app score and current non-resolved findings without uploading, matching or recording a verdict. It needs a full credential from login; upload-only tokens cannot read findings. Omit --name only when your account has one app. The API equivalent is GET /api/v1/apps/:id/findings.

JSON schemaVersion 1 contains app, scanDate, processing, processingReason, score, findings and verificationLimits. Findings include alert and advisory IDs, severity and its source, installedVersion, fixedIn, fixGuidance, classification and evidence limits. Unknown values remain null or explicitly unknown.

The server does not receive file paths or dependency trees. When run in the matching checkout, the CLI can add manifestFile, lockfile, localEvidence and affectedDependencyPaths from npm package-lock v2/v3 files. Those paths are installation locations, not a complete dependency graph or a runtime call path. Other lockfile formats currently retain unknown path evidence.

What the evidence proves

A vulnerable-version match is not confirmed exploitability. A lockfile records a resolved version; it does not prove that version is deployed or that vulnerable code executes. Runtime-declared and development classifications come from dependency metadata, not runtime observation. Development dependencies can affect builds and CI.

Check advisory exploit conditions, exposed inputs, configuration and actual runtime, build or CI use. Never claim a call path is safe without supporting evidence. Missing version or path evidence is a limit, not a safety result.

Score and recommended actions

scoreBefore and scoreAfter use the app’s actual scoring model. The explanation lists penalty factors and ranks actions by supported score gain. Package estimates remove that package’s scored alerts while holding other inputs unchanged and applying the same caps and rounding. Estimates are independent, not additive. A useful security fix can earn zero points while a penalty cap still applies.

Freshness has no numeric action estimate. End-of-life and unresolved-version estimates describe clearing the whole respective penalty, not a promise about a particular upgrade. Pending or unavailable scores are null. Score improvement and security risk are separate decisions.

JSON and errors

findings --json, review --json, upload --json and scan --upload --json emit one JSON document on stdout without progress messages. scan --json alone prints the manifest. JSON mode cannot be combined with --watch or --all. Successful commands exit 0, including accepted uploads whose processing is pending. Failures exit 1.

npx vibebeacon@latest login

An invalid key names that reconnect command. Remove an old --key flag or VIBEBEACON_API_KEY override before retrying. Human errors go to stderr; JSON errors use schemaVersion, error.code, error.message and, for invalid credentials, error.reconnectCommand. Keys and server response bodies are not echoed. Node exits normally so pending Windows handles can close.