Documentation

CLI Usage

Scan any npm package, GitHub repo, or local directory. No install required.

Scan a package

npx skillsafe scan @modelcontextprotocol/server-filesystem
npx skillsafe scan chalk
npx skillsafe scan ./my-local-project

JSON output

For CI/CD integration or piping to other tools.

npx skillsafe scan axios --json | jq '.overallScore'

Skip dependency analysis

Faster scans by skipping npm audit and typosquatting checks.

npx skillsafe scan my-package --skip-deps

Exit codes

The CLI exits with code 1 if the package scores below 40 (Blocked grade). Use this in CI pipelines to gate installs.

npx skillsafe scan suspicious-pkg || echo "BLOCKED"

Web Scanner

Visit safeskill.dev and paste any npm package name. The scanner downloads the package, runs all 16 detectors, and shows a full report.

How it works

1. You enter a package name in the search bar
2. The API checks for a cached result in Google Cloud Storage
3. If not cached, a Cloud Run worker downloads and scans the package
4. Results are stored in GCS (full report) and Firestore (metadata)
5. The report is displayed with score breakdown, findings, permissions, and taint flows

Cached results

Scanned packages get a permanent URL at /scan/package-slug. These pages are pre-rendered with full SEO metadata (Open Graph, Twitter cards, structured data) and load instantly.

Badges for your README

[![SafeSkill](https://safeskill.dev/api/badge/YOUR-PACKAGE)](https://safeskill.dev/scan/YOUR-PACKAGE)

Scoring System

Every package gets a 0-100 score computed from 8 weighted factors. Higher is safer.

Grades

A single critical prompt injection finding with high confidence caps the score at 30. Each additional finding of the same severity has diminishing impact (67% of previous).

Detectors

Code detectors (8)

AST-based static analysis using ts-morph. Runs on every .js, .ts, .mjs, .cjs file.

Prompt injection detectors (8)

Pattern matching on README, skills.md, CLAUDE.md, and other content files.

API Reference

The SafeSkill API is a Cloudflare Worker that reads from GCS/Firestore and enqueues scans to Cloud Run via Cloud Tasks.

{ "package": "@modelcontextprotocol/server-filesystem" }

// Response 200 (cached):
{ "status": "completed", "slug": "...", "result": { ... } }

// Response 202 (queued):
{ "status": "queued", "jobId": "abc123", "slug": "..." }

{ "packages": ["chalk", "axios", "zod", ...] }

// Response 202:
{ "queued": 47, "skipped": 3, "jobs": [...] }

Self-Hosting

SafeSkill is fully open source. Run the entire stack yourself.

Prerequisites

• Node.js 18+
• pnpm
• GCP account (for Cloud Run, GCS, Firestore, Cloud Tasks)
• Cloudflare account (for Pages and Workers)

Setup

git clone https://github.com/OyadotAI/safeskill
cd safeskill
make setup    # install + build + crawl 10K skills

# Copy and configure environment
cp apps/api-worker/wrangler.toml.example apps/api-worker/wrangler.toml
cp apps/web/wrangler.jsonc.example apps/web/wrangler.jsonc
# Edit both files with your GCP project ID, bucket, etc.

Deploy

# 1. Deploy scanner to Cloud Run
make deploy-scanner

# 2. Set up the API worker secret
cd apps/api-worker
wrangler secret put GCP_SERVICE_ACCOUNT_KEY < path/to/key.json
wrangler deploy

# 3. Deploy the web frontend
NEXT_PUBLIC_API_URL=https://your-api.workers.dev make deploy

GCP resources needed

• Cloud Run service (2GB RAM, 180s timeout, 100 max instances)
• Cloud Storage bucket for scan results
• Firestore database for metadata and job tracking
• Cloud Tasks queue for async scan orchestration
• Service account with Storage, Firestore, and Cloud Tasks permissions

Contributing

Contributions welcome. The codebase is a pnpm monorepo with Turbo for builds.

git clone https://github.com/OyadotAI/safeskill
cd safeskill
pnpm install
pnpm build
make dev      # starts the web app at localhost:3000
make scan PKG=chalk   # test the CLI scanner

Project structure

packages/
  scanner/        # Core analysis engine (ts-morph, 3-layer pipeline)
  cli/            # The `skillsafe` npm command
  shared/         # Types, constants, validation (Zod)
  scan-store/     # Storage interface + GCS/Firestore implementation
apps/
  web/            # Next.js frontend (Cloudflare Pages)
  api-worker/     # Cloudflare Worker API
  scanner-worker/ # Cloud Run container (Dockerfile)
scripts/
  seed.ts         # Crawl 10K+ skills from npm/Smithery/GitHub
  scan-packages.ts     # Batch scan CLI
  migrate-to-gcs.ts    # Migrate JSON → GCS + Firestore
  generate-sitemap.ts  # Generate sitemap.xml