ExploitGrid Dependency Scanner

The ExploitGrid Dependency Scanner is a native GitHub Action that analyzes your Node.js manifest files (package.json and package-lock.json) for known vulnerabilities. It leverages ExploitGrid's threat intelligence to identify CISA KEVs (Known Exploited Vulnerabilities) and public Proof-of-Concept (PoC) exploits, allowing you to block high-risk pull requests automatically.

Prerequisites

1. ExploitGrid API Key: You must have an active API key from ExploitGrid. Note that the CI scanning endpoint is restricted from Free tier accounts.
2. GitHub Secrets: Navigate to your repository's Settings > Secrets and variables > Actions, and add your API key as a new repository secret named EXPLOITGRID_API_KEY.

Usage

Create a new workflow file in your repository under .github/workflows/exploitgrid-scan.yml and add the following configuration. This example runs on both pushes to main and all pull requests.

name: ExploitGrid Security Scan

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read       # Required for actions/checkout on private repos
      checks: write        # Required to publish Check annotations
      pull-requests: write # Required for PR status reports

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run ExploitGrid Scanner
        uses: Nebulark-net/exploitgrid_dependency_action@v1
        with:
          api_key: ${{ secrets.EXPLOITGRID_API_KEY }}
          # Optional inputs (uncomment if needed):
          # manifest_path: './'
          # include_dev_dependencies: 'false'
          # fail_threshold: 'exploit_or_kev'
          # fail_on_error: 'true'

Input Configuration

Input	Required	Default	Description
api_key	Yes	N/A	Your ExploitGrid API Key (must be stored as a GitHub Secret).
github_token	No	${{ github.token }}	Token used to publish annotations via the GitHub Checks API.
manifest_path	No	./	The directory path containing your package.json and package-lock.json.
include_dev_dependencies	No	'false'	Set to 'true' to include devDependencies in the vulnerability scan.
fail_threshold	No	'exploit_or_kev'	Determines the gating condition for failing the workflow. See modes below.
fail_on_error	No	'true'	Set to 'false' to prevent workflow failure if the ExploitGrid API is unreachable.

Failure Threshold Modes

The fail_threshold input dictates exactly when the GitHub Action should block a merge by returning a non-zero exit code.

• kev_only: Fails the pipeline only if a discovered vulnerability is actively listed on the CISA KEV (Known Exploited Vulnerabilities) catalog.
• exploit_or_kev (Default): Fails the pipeline if a vulnerability is on the CISA KEV list OR if a public exploit (PoC) is available.
• critical_or_exploited: Fails the pipeline if a vulnerability has an ExploitGrid composite severity of CRITICAL, OR if a public exploit is available.
• none: The scanner will analyze dependencies, publish inline annotations, and generate the Step Summary, but will never fail the workflow step.