Integrate GeekWala into Your Workflow

Creating API Tokens

5. Set expiration: 30 days, 90 days, 1 year, or no expiry

6. Click Create and copy the token immediately (shown only once)

Using API Tokens

Include the token in the Authorization header of all API requests:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://www.geekwala.com/api/v1/projects

Base URL

https://www.geekwala.com/api/v1

Pagination

List endpoints support pagination with query parameters:

Offset Pagination (scan lists)

• • page - Page number (default: 1)
• • per_page - Items per page (default: 50, max: 100)

GET /api/v1/projects/{project}/scans?page=2&per_page=50

Cursor Pagination (scan results)

Scan results use cursor-based pagination for efficient large result sets. Use the cursor value from the links.next URL to fetch subsequent pages.

• • per_page - Items per page (default: 100, max: 500)
• • cursor - Pagination cursor from previous response

GET /api/v1/scans/{id}/results?per_page=100&cursor=eyJpZCI6MTAwfQ

Project Endpoints

Scan Endpoints

Vulnerability Endpoints

Rate Limit Headers

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1609459200

Handling 429 Responses

When you exceed the rate limit, the API returns HTTP 429 with a Retry-After header.

async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;

    const retryAfter = response.headers.get('Retry-After');
    await new Promise(resolve =>
      setTimeout(resolve, (retryAfter || (i + 1)) * 1000)
    );
  }
  throw new Error('Max retries exceeded');
}

GitHub Actions (Recommended)

The official geekwala/scan-action is a thin wrapper around the geekwala CLI. Point it at your manifest or lockfile and your GeekWala project, and it scans for vulnerabilities enriched with EPSS and CISA KEV data.

name: Security Scan
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write # required for upload-sarif

    steps:
      - uses: actions/checkout@v4

      - name: GeekWala Security Scan
        uses: geekwala/scan-action@v1
        id: scan
        with:
          manifest-path: package-lock.json
          project-id: ${{ vars.GEEKWALA_PROJECT_ID }}
          api-token: ${{ secrets.GEEKWALA_TOKEN }}
          fail-on: high

      - name: Upload SARIF to GitHub
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: ${{ steps.scan.outputs.sarif-path }}

fail-on gates the step itself (critical|high|medium|low); omit it to always succeed and rely on the Security tab / PR annotations instead. if: always() on the upload step lets the report reach the Security tab even when the scan step fails the job.

Action Inputs & Outputs

Outputs: findings-count (total SARIF results) and sarif-path (path to the generated SARIF 2.1.0 report, for upload-sarif).

Monorepo Support

There's no auto-detection — point manifest-path at the specific lockfile you want scanned. For a monorepo, that's usually a nested path:

- uses: geekwala/scan-action@v1
  with:
    manifest-path: packages/api/package-lock.json
    project-id: ${{ vars.GEEKWALA_PROJECT_ID }}
    api-token: ${{ secrets.GEEKWALA_TOKEN }}

Add one job per package if you want each scanned into a separate GeekWala project.

GitLab CI

No native GitLab template is published yet — run the CLI directly in your .gitlab-ci.yml. Set GEEKWALA_TOKEN and GEEKWALA_PROJECT_ID in CI/CD Variables (masked). This works today even where GitLab's own native dependency scanning is gated behind the Ultimate tier.

vulnerability_scan:
  stage: test
  image: node:22-alpine
  script:
    - npx --yes geekwala@latest scan package-lock.json --project "$GEEKWALA_PROJECT_ID" --fail-on high
  # Omit --fail-on for a report-only run; allow_failure: true also works for non-blocking scans.

Jenkins Pipeline

Add the token as a Jenkins credential (e.g. geekwala-token) and run the CLI via a sh step. Requires Node.js >= 22 on the agent.

pipeline {
  agent any
  environment {
    GEEKWALA_TOKEN = credentials('geekwala-token')
    GEEKWALA_PROJECT_ID = '123'
  }
  stages {
    stage('Vulnerability Scan') {
      steps {
        sh 'npx --yes geekwala@latest scan package-lock.json --project "$GEEKWALA_PROJECT_ID" --fail-on high'
      }
    }
  }
}

The CLI's own exit code fails the stage when --fail-on's threshold is met — no extra parsing needed. Add --sarif > geekwala.sarif and archive the file as a build artifact if you want a durable report.