scalp audit

Validate SCAL-P lockfile hashes against node_modules, detect tampering, and generate reports.

Verifies that your installed packages match the expected hashes recorded in .scalp/lockfile.json. If someone or something modified a package after installation — malicious script, accidental edit, corrupted download — scalp audit catches it.

Usage

scalp audit [flags]

Flags

Flag	Default	Description
`--pm`	auto-detected	Package manager override
`--policy`	`.scalp/policy.json`	Policy path
`--ci`	false	Force enforcement to `block`
`--report`	""	Report output path (`.md`, `.sarif`). Use `-` for stdout
`--artifact`	""	Binary artifact to verify alongside packages
`--checksum`	""	Checksums file for binary verification

Basic audit

scalp audit

On success:

audit ok

On tampering detected (warn mode):

! policy violations detected
policy violations detected:
- lodash@4.17.21 (hash_mismatch: hash_check)

On tampering detected (block mode via --ci):

ci failed: [{"PackageID":"lodash@4.17.21","Reason":"hash_mismatch","Rule":"hash_check"}]

Detecting tampering

Here's a real scenario. You install lodash, then someone modifies a file:

# Install normally
scalp install

# Someone tampered with lodash
echo "malicious code" >> node_modules/lodash/index.js

# Audit catches it
scalp audit

! policy violations detected
policy violations detected:
- lodash@4.17.21 (hash_mismatch: hash_check)

This also detects files added or removed from a package directory. If a postinstall script creates a new file inside a package, the hash changes and scalp audit flags it.

Audit with report

Generate a Markdown report:

scalp audit --report audit-report.md

Write to stdout:

scalp audit --report -

The report includes:

Summary table (verified, mismatched, missing)
Per-package hash verification status
Trust scores with breakdown
CVE table
Policy JSON
All violations
Full event log

Audit + binary verify

You can audit packages and verify a binary artifact in a single command:

scalp audit \
  --artifact scalp_linux_amd64.tar.gz \
  --checksum checksums.txt \
  --report audit-report.md

This runs both checks and produces one unified report with both results.

Audit in CI

scalp audit --ci

Forces enforcement to block. If any hash mismatch is found, exit code is 1.

Audit with enforcement

Default enforcement is warn (print and continue). With --ci or block in policy:

scalp audit --ci

On mismatch:

ci failed: [{"PackageID":"lodash@4.17.21","Reason":"hash_mismatch","Rule":"hash_check"}]

Exit code 1.

How hash verification works

SCAL-P reads .scalp/lockfile.json to get expected hashes
It runs the dependency tree command (npm ls --all --json, etc.) to list installed packages
For each package, it hashes the directory on disk using SHA-512 via hash.Dir()
It compares the computed hash against the lockfile entry
Results: verified (match), mismatched (different hash), or missing (no lockfile entry or directory not found)