Clone or download the code without running it, scan the directory with the Safeguard CLI, and read the findings before you install anything. A directory scan reads files on disk, and the idea is to look before any install script has had a chance to run.
Is there a single command that vets one package?
Not that the docs show. The documented route is to scan code you have fetched: a directory, a repository URL, a container image or an SBOM file. That works well for a package you are about to adopt, because you can inspect its source and its own dependency manifest. For a lookup by name, the Gold Open Source directory is free and needs no login.
How do you install the CLI?
From the CLI docs at cli.safeguard.sh. On macOS or Linux:
curl -fsSL https://cli.safeguard.sh/install | bash
On Windows:
irm https://cli.safeguard.sh/install.ps1 | iex
To read the script first, download it to a file and open it. The installer detects your platform, fetches the latest release or the one set in SAFEGUARD_VERSION, verifies a checksum, and aborts on a mismatch. The docs list darwin, linux and windows builds and say a package on npm is coming. Run safeguard login to authenticate, using the OAuth device flow.
How do you scan something you have not installed?
Fetch the source into a scratch folder. Many registries let you download a package archive without installing it, or you can clone the repository. Do not run its setup scripts. Then scan:
safeguard scan --dir ./candidate --output out/
The docs also show safeguard scan --repo URL for a repository and safeguard scan --sbom FILE for SPDX or CycloneDX documents.
What do you read afterwards?
The output directory holds sbom.json and findings.json, and per component files named vuln.json, license.json, secret.json and scorecard.json. Read them in this order:
- secret.json, because an embedded credential is an immediate red flag.
- vuln.json, which the docs describe as grype-compatible under .data.matches.
- license.json, to see whether the license fits your use.
- scorecard.json, as a signal of how the project is run.
Run safeguard update first so the local vulnerability database is fresh.
What does a clean result prove?
Less than people hope. A scan reports known issues in known components and detected secrets. It does not prove an unknown package is benign. Combine it with plain checks: who maintains it, when it last changed, whether the name is one letter off from a popular package.
What to do
- Install the CLI and sign in.
- Run safeguard update to refresh the databases.
- Download the package source into an isolated folder without installing it.
- Scan the folder and read secret.json, vuln.json, license.json and scorecard.json.
- Look the package up on Gold Open Source for CVEs and malware flags.
- Decide, and record the version you checked.
- In CI, use the jq gate from the docs to fail on critical findings.
What if the scan finds something?
Do not panic and do not ignore it. First check whether the finding is in the package itself or in one of its dependencies, and whether it affects the version you want. A vulnerability in a test-only dependency matters less than one in a runtime path.
Second, look for a fixed version. If the maintainers have released one, pick it. If not, check whether the issue is reachable in your use. Reachability analysis in Safeguard exists for this question, and the CLI documents a fix command that can update vulnerable packages in a project you own.
Third, decide on a rule. For a critical finding with no fix, the usual answer is to choose another package or accept the risk in writing with an owner and a date.
A secret in secret.json deserves different treatment. If the package ships with a live credential, report it to the maintainers and do not use it.
Quick check
Does scanning run the package's code?
A scan reads files. Do not run install scripts on a package you are still evaluating.
Is there an npm install for the CLI?
The CLI docs list npm as coming soon. Use the installer for now.
Sources
Last reviewed: 18 October 2026.
