kitchencoder/package-scan repository overview

⁠package-scan

Multi-Ecosystem Package Threat Scanner.

• Detects known-compromised packages across npm, Maven/Gradle, and Python by comparing your codebase to curated threat CSVs.
• Runs fully in a container to avoid polluting the host with dependencies—ideal for quick, disposable scans on personal machines.

⁠Usage

⁠Basic Scan

Scan for all threats across all detected ecosystems:

docker run --rm -v "$(pwd):/workspace" kitchencoder/package-scan:latest

⁠Scan for Specific Threat

Focus on a specific supply chain attack (e.g., sha1-Hulud):

docker run --rm -v "$(pwd):/workspace" kitchencoder/package-scan:latest --threat sha1-Hulud

⁠Scan Specific Ecosystem

Target a specific package ecosystem:

# Scan only npm packages
docker run --rm -v "$(pwd):/workspace" kitchencoder/package-scan:latest --ecosystem npm

# Scan only Java packages (Maven/Gradle)
docker run --rm -v "$(pwd):/workspace" kitchencoder/package-scan:latest --ecosystem maven

# Scan only Python packages
docker run --rm -v "$(pwd):/workspace" kitchencoder/package-scan:latest --ecosystem pip

⁠List Compromised Packages

View all packages in the embedded threat database:

# Formatted display
docker run --rm kitchencoder/package-scan:latest --list-affected-packages

# Raw CSV output (for piping/saving)
docker run --rm kitchencoder/package-scan:latest --list-affected-packages-csv > threats.csv

⁠Custom Threat Database

docker run --rm \
  -v "$(pwd):/workspace" \
  -v "$(pwd)/custom-threat.csv:/app/custom.csv" \
  kitchencoder/package-scan:latest --csv /app/custom.csv

⁠Save Report to Host

docker run --rm -v "$(pwd):/workspace" \
  kitchencoder/package-scan:latest --output /workspace/report.json

# Report saved at: ./report.json on your host

⁠Accurate file paths in the report

docker run --rm \
  -v "$(pwd):/workspace" \
  -e SCAN_PATH_PREFIX="$(pwd)" \
  kitchencoder/package-scan:latest

# Paths in the report reflect your filesystem not Dockers

⁠What Gets Scanned

⁠npm (JavaScript/Node.js)

• Manifests: package.json
• Lock files: package-lock.json, yarn.lock, pnpm-lock.yaml
• Installed: node_modules/

⁠Maven/Gradle (Java)

• Manifests: pom.xml, build.gradle, build.gradle.kts
• Lock files: gradle.lockfile

⁠pip (Python)

• Manifests: requirements.txt, pyproject.toml, Pipfile, environment.yml
• Lock files: poetry.lock, Pipfile.lock

⁠When to Use It

• There's new supply chain attack (e.g., sha1-Hulud) and you need fast assurance that your local projects are clean.
• You want a repeatable, isolated scan without installing Python or ecosystem-specific tooling.
• You’re triaging multiple projects and need uniform reports (package_scan_report.json) to share with security or leadership.
• You have a custom threat CSV from your team or vendor and want to validate it quickly.

⁠When Not to Use It

• Routine vulnerability management or CVE monitoring (use Snyk, Dependabot, or native audit tools).
• SBOM generation, static analysis, or license compliance (use Syft/CycloneDX, Semgrep/CodeQL, or license scanners).
• Deep ecosystem-specific dependency verification that requires full builds or private registries.

⁠Interpreting Results

• Findings are grouped by ecosystem and source (manifest, lockfile, installed). Review matching package/version, declared spec, and file path.
• Exit code is non-zero when threats are found—useful for CI or pre-commit checks.
• Default report path: /workspace/package_scan_report.json (mapped to your current directory in the examples above).

⁠Safety Notes

• Container runs with a bind mount to read your project; it does not modify files unless you specify an output path in that mount.
• Avoid passing sensitive threat feeds unless you trust the environment; use --no-save to skip writing reports to disk when handling secrets.
• Keep Docker updated and pull fresh images before scanning during active incidents to ensure you have current threat intelligence or use your own threat csv.

⁠Source Code

https://github.com/thekitchencoder/package-scan⁠