Skip to main content
Glama

lazaretto

by io.github.jamesdfinance-dev
OverviewDiscussionsAdmin

scan_lockfile_deep

Behaviorally scan the exactly-pinned dependencies in a lockfile, not just their identities: reads the code of each package and screens for credential theft, exfiltration, obfuscation, prompt injection and install-time droppers. Each result carries a verdict, a risk level, the ids of the rules that fired and a risk summary. It does not carry file-and-line evidence: for that, run scan_artifact on the package you want to look at. This is the paid counterpart to check_lockfile, which only matches names and versions against advisories. Metered: one credit per package that returns a verdict, nothing for one that errors. Capped at 25 packages per call, in lockfile order, so calling it again with the same lockfile rescans the same first 25. To continue, pass the not_scanned.packages list from the result (name@version strings) as packages instead of lockfile. Use it before installing a tree you have not vetted.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
lockfileNoThe full text contents of a package-lock.json, yarn.lock, or pnpm-lock.yaml. Give this or packages.
packagesNoExactly pinned name@version strings, for example ["chalk@5.6.1", "@scope/name@1.0.0"]. Use it to continue a capped run with the not_scanned.packages list from the previous result. Give this or lockfile.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
erroredNo
resultsYes
scannedYes
not_scannedNoWhat was left out and why. null when nothing was.
ways_to_payNoPresent only when the key ran out of credits partway: how to buy credits for the rest.
refund_failedNoTrue when those credits could not be returned automatically; refund_note says what to do.
worst_verdictNo
billed_creditsYes
refunded_creditsNoCredits reserved for packages that were not billed (errored or not started) and were given back.
complete_coverageYes
remaining_creditsNo
auto_reload_possibleNoOn an error result (batch_failed) only, present and true when the key has auto-reload switched on. "Nothing was billed" there means no scan credits; with this set, reserving them may have started a reload, and if it did, that pack was charged to the saved card and its credits are on the key.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedOutput schema / properties / auto_reload_possible
      Added value: +{
+  "description": "On an error result (batch_failed) only, present and true when the key has auto-reload switched on. \"Nothing was billed\" there means no scan credits; with this set, reserving them may have started a reload, and if it did, that pack was charged to the saved card and its credits are on the key.",
+  "type": "boolean"
+}
    • changedOutput schema / properties / not_scanned / properties / packages / description
      Previous value: -"name@version of each package not scanned, in lockfile order, at most 200."New value: +"name@version of every package not scanned, in lockfile order."
  2. Changed9 schema fields changed
    • changedInput schema / properties / lockfile / description
      Previous value: -"The full text contents of a package-lock.json, yarn.lock, or pnpm-lock.yaml."New value: +"The full text contents of a package-lock.json, yarn.lock, or pnpm-lock.yaml. Give this or packages."
    • addedInput schema / properties / packages
      Added value: +{
+  "description": "Exactly pinned name@version strings, for example [\"chalk@5.6.1\", \"@scope/name@1.0.0\"]. Use it to continue a capped run with the not_scanned.packages list from the previous result. Give this or lockfile.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • removedInput schema / required
      Removed value: -[
-  "lockfile"
-]
    • changedOutput schema / properties / not_scanned / description
      Previous value: -"What was left out and why."New value: +"What was left out and why. null when nothing was."
    • addedOutput schema / properties / not_scanned / properties
      Added value: +{
+  "by_reason": {
+    "description": "count split by cause; the three always sum to count.",
+    "properties": {
+      "cap": {
+        "type": "integer"
+      },
+      "credits": {
+        "type": "integer"
+      },
+      "time": {
+        "type": "integer"
+      }
+    },
+    "type": "object"
+  },
+  "count": {
+    "description": "Unique packages not scanned.",
+    "type": "integer"
+  },
+  "packages": {
+    "description": "name@version of each package not scanned, in lockfile order, at most 200.",
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  },
+  "reasons": {
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  }
+}
    • addedOutput schema / properties / refund_failed
      Added value: +{
+  "description": "True when those credits could not be returned automatically; refund_note says what to do.",
+  "type": "boolean"
+}
    • changedOutput schema / properties / refunded_credits / description
      Previous value: -"Credits reserved for packages that errored and were given back."New value: +"Credits reserved for packages that were not billed (errored or not started) and were given back."
    • addedOutput schema / properties / results / items / properties / risk_summary
      Added value: +{
+  "description": "One line on why the risk is what it is. Run scan_artifact for file-and-line evidence.",
+  "type": "string"
+}
    • addedOutput schema / properties / ways_to_pay
      Added value: +{
+  "description": "Present only when the key ran out of credits partway: how to buy credits for the rest.",
+  "type": "object"
+}
  3. Added

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses metering (one credit per verdict, nothing for errors), the 25-package cap, lockfile-order rescanning behavior, and the continuation mechanism. It also describes what the result carries and deliberately does not carry (file-and-line evidence). None of this contradicts the provided annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence carries operational substance: purpose, result shape, excluded evidence, paid/free counterpart, metering, cap, continuation, and timing. It is dense without filler, though the metering and cap rules could be slightly more scannable in list form.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's metering, cap, continuation flow, and sibling alternatives, the description provides nearly all guidance an agent needs to select and invoke it correctly. The only minor gap is the undefined behavior when both `lockfile` and `packages` are supplied, but the phrasing covers typical usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds real value by explaining that repeating `lockfile` rescans the same first 25 packages and that `packages` takes name@version strings from the previous result's not_scanned.packages. The 'give this or packages' phrasing conveys the either/or intent, though it does not explicitly state the behavior if both are supplied.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: behaviorally scan exactly-pinned dependencies in a lockfile and screen package code for five named threat classes. It explicitly distinguishes itself from scan_artifact (no file-and-line evidence) and check_lockfile (only name/version advisory matching), so an agent can select it unambiguously.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It says when to use it ('before installing a tree you have not vetted'), when to use scan_artifact instead (for file-and-line evidence), and how it differs from the free check_lockfile. It also gives the exact continuation workflow: pass the not_scanned.packages list as `packages` instead of `lockfile`.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All lazaretto toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources