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/security-scan-action scans your dependencies for vulnerabilities enriched with EPSS and CISA KEV data. It auto-detects your manifest or lockfile from the repo root, so the only input it requires is an API token.

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/security-scan-action@v1
        id: scan
        with:
          api-token: ${{ secrets.GEEKWALA_TOKEN }}
          severity-threshold: high
          sarif-file: geekwala.sarif

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

severity-threshold gates the step itself (none|low|medium|high|critical); omit it to always succeed and rely on the Security tab / PR annotations instead. fail-on-kev and epss-threshold gate on exploitation signals instead of raw severity. 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 include scan-status (PASS|FAIL|ERROR), has-vulnerabilities, per-severity counts such as critical-count and high-count, and sarif-file (path to the generated SARIF report, for upload-sarif).

Monorepo Support

The action auto-detects a dependency file at the repo root. In a monorepo that is usually the wrong one, so point file-path at the lockfile you actually want scanned:

- uses: Geekwala/security-scan-action@v1
  with:
    api-token: ${{ secrets.GEEKWALA_TOKEN }}
    file-path: packages/api/package-lock.json

Add one step per package to scan several workspaces in the same job.

GitLab CI

No native GitLab template or CLI package is published yet — call the REST API directly from your .gitlab-ci.yml script. 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
  script:
    - |
      curl -sf -X POST "https://www.geekwala.com/api/v1/projects/$GEEKWALA_PROJECT_ID/scans" \
        -H "Authorization: Bearer $GEEKWALA_TOKEN" \
        -H "Content-Type: application/json"
  # See the API Endpoints reference above for polling GET /scans/{id}/results and building your
  # own severity gate from the response; allow_failure: true works for non-blocking scans.

Jenkins Pipeline

Add the token as a Jenkins credential (e.g. geekwala-token) and call the REST API via a sh step — no CLI package is published yet, so curl is all you need.

pipeline {
  agent any
  environment {
    GEEKWALA_TOKEN = credentials('geekwala-token')
    GEEKWALA_PROJECT_ID = '123'
  }
  stages {
    stage('Vulnerability Scan') {
      steps {
        sh '''
          curl -sf -X POST "https://www.geekwala.com/api/v1/projects/$GEEKWALA_PROJECT_ID/scans" \
            -H "Authorization: Bearer $GEEKWALA_TOKEN" \
            -H "Content-Type: application/json"
        '''
      }
    }
  }
}

See the API Endpoints reference above for polling GET /scans/{id}/results and failing the stage on a severity threshold from the response — curl -f only fails the step on an HTTP error, not on findings.