reposhield

CLI for RepoShield — scan any GitHub repository for malicious code, exfiltration payloads, exposed secrets, and supply-chain risks before you npm install.

43 checks across 7 layers (install hooks, dangerous code, network indicators, dependencies via OSV, CI/CD hardening, exposed secrets, repo-surface signals). Free, no signup.

Quickstart

No install needed — runs through npx:

npx shieldrepo https://github.com/sindresorhus/slugify

Short form (owner/repo):

npx shieldrepo expressjs/express

Machine-readable JSON (for CI pipelines):

npx shieldrepo vercel/next.js --json > report.json

With a Pro API key (private repos / unlimited rate limit):

REPOSHIELD_API_KEY=rs_... npx shieldrepo owner/private-repo
# or
npx shieldrepo owner/private-repo --key rs_...

Flags

| Flag | Default | What it does | |---|---|---| | --json | off | Print full ScanResult JSON to stdout (no progress to stderr). | | --quiet / -q | off | Suppress banner and progress bar. | | --key <KEY> / -k <KEY> | unset | API key. Falls back to REPOSHIELD_API_KEY env var. | | --fail-on <level> | caution | Exit non-zero on this verdict or worse. One of trust, caution, danger. | | --timeout <seconds> | 90 | Abort scan after N seconds. Network or CPU stall safety. | | --version | — | Print version + exit. | | --help | — | Print full help. |

Exit codes

| Code | Meaning | |---|---| | 0 | trust — safe to install | | 1 | caution — review findings before installing | | 2 | danger — do not install without review | | 3 | scan_error — network, auth, bad URL, or timeout (the tool itself failed) |

CI distinguishes "your repo is bad" (1, 2) from "the tool failed" (3) so a flaky network doesn't block your release pipeline.

CI integration

GitHub Actions

name: supply-chain-audit
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx shieldrepo ${{ github.repository }} --fail-on danger
        env:
          REPOSHIELD_API_KEY: ${{ secrets.REPOSHIELD_API_KEY }}

GitLab CI

reposhield:
  image: node:20
  script:
    - npx shieldrepo $CI_PROJECT_PATH --fail-on caution --json > report.json
  artifacts:
    paths: [report.json]
  variables:
    REPOSHIELD_API_KEY: $REPOSHIELD_API_KEY

CircleCI

jobs:
  audit:
    docker: [{ image: cimg/node:20.0 }]
    steps:
      - run: npx shieldrepo $CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME --timeout 120

API endpoint

By default the CLI talks to https://reposhield.app. Override with REPOSHIELD_API_BASE for self-hosting or staging:

REPOSHIELD_API_BASE=https://staging.reposhield.app npx shieldrepo ...

Rate limits

• Anonymous: 3 scans/day per IP
• Free signed-in account: 10 scans/day
• Pro: 100/day + /api/v1/scan REST API
• Team: 1000/day + Team-tier checks

Upgrade: https://reposhield.app/pricing

What it does NOT do

• Does not download or execute the repo on your machine.
• Does not scan the npm tarball — only the GitHub repo source. (Tarball scanning ships in v1.1.)
• Does not require auth tokens for public repos.

Methodology + every check ID with confidence label: https://reposhield.app/methodology

License

Apache-2.0. See LICENSE.