> ## Documentation Index
> Fetch the complete documentation index at: https://docs.custoden.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Block risky packages in CI

> Fail a pull request when it adds or upgrades an npm package that is malicious or suspicious.

> [!TIP]
>
> The [GitHub Action](https://docs.custoden.com/guides/github-action.md) does this for you, and also checks files that run during CI.

The free tier allows 100 units a day per IP, so check only the dependencies a pull request changes, not the whole lockfile.

## Script

Save as `scripts/check-deps.mjs`. It compares `package-lock.json` with the base branch and checks every new or changed version.

```js theme={null}
import { execSync } from 'node:child_process'
import { readFileSync } from 'node:fs'

const base = process.env.BASE_REF || 'origin/main'
const read = (src) => JSON.parse(src).packages ?? {}
const before = read(execSync(`git show ${base}:package-lock.json`).toString())
const after = read(readFileSync('package-lock.json', 'utf8'))

const changed = new Map()
for (const [path, meta] of Object.entries(after)) {
  if (!path || !meta.version || meta.link) continue
  if (before[path]?.version === meta.version) continue
  const name = meta.name ?? path.slice(path.lastIndexOf('node_modules/') + 13)
  changed.set(`${name}@${meta.version}`, { ecosystem: 'npm', name, version: meta.version })
}

const packages = [...changed.values()]
console.log(`Checking ${packages.length} new or changed packages`)

let failed = false
for (let i = 0; i < packages.length; i += 10) {
  const res = await fetch('https://api.custoden.com/v1/packages/check', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ packages: packages.slice(i, i + 10) }),
  })
  if (res.status === 429) {
    console.log(`Rate limited. Retry after ${res.headers.get('retry-after')} seconds.`)
    process.exit(1)
  }
  const { results } = await res.json()
  for (const { input, report, error } of results) {
    if (error) {
      console.log(`? ${input.name}@${input.version}: ${error.message}`)
      continue
    }
    if (report.verdict === 'malicious' || report.verdict === 'suspicious') {
      failed = true
      console.log(`x ${report.name}@${report.version}: ${report.verdict}`)
      for (const f of report.findings) console.log(`    ${f.severity} ${f.title}`)
    }
  }
}

process.exit(failed ? 1 : 0)
```

## Workflow

```yaml theme={null}
name: Dependency check
on:
  pull_request:
    paths: [package-lock.json]
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
        with:
          fetch-depth: 0
          persist-credentials: false
      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4
        with:
          node-version: 22
      - run: node scripts/check-deps.mjs
        env:
          BASE_REF: origin/${{ github.base_ref }}
```

## Choosing what to block

| Verdict | Suggested handling |
| - | - |
| `malicious` | Always fail |
| `suspicious` | Fail, and let a maintainer override after review |
| `review` | Print a warning |
| `ok` | Pass |

To also fail on known vulnerabilities, check `report.risk` instead of `report.verdict`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.