Meerkat Technical Reference

Overview

Meerkat is a dependency-tracking platform for your Git repositories. It scans repositories across configured repository groups, extracts all project dependencies, and presents them through a web interface — enabling rapid identification of which projects are affected when a package has a known security threat.

Key capabilities:

• Projects Dashboard — view all scanned projects with their dependencies, versions, and ecosystems
• Hunt — search for packages across all repos to identify exposure instantly
• Allow List & Policy Enforcement — curate approved dependencies and enforce them via CI
• Vulnerability Threat Feed — auto-subscribe to malware reports from a vulnerability intelligence feed
• CI Agent — gate CI pipelines on policy compliance
• Notifications — email and chat alerts for violations and new malware

Prerequisites

Before deploying Meerkat, ensure you have:

• Docker and Docker Compose installed
• A Git hosting platform Personal Access Token (PAT) with read_api scope
• A PostgreSQL database (provided automatically by the devcontainer)
• OIDC client credentials from your identity provider

For local development, VS Code with the Dev Containers extension is recommended — no local tool installation required.

Quick Start

The fastest way to run Meerkat locally is via the VS Code devcontainer:

1. Clone the repository

git clone https://git.internal/your-group/meerkat.git
cd meerkat

2. Create your .env file

cp .env.example .env
# Edit .env and fill in real values

3. Open in devcontainer

Open the project folder in VS Code. When prompted, click "Reopen in Container". The devcontainer will build the Go backend and PostgreSQL services, run DB migrations, and install all required tooling automatically.

4. Start the server

cd backend && go run main.go

The server will be available at http://localhost:8080.

Environment Variables

All secrets must be provided via a .env file (gitignored). Copy .env.example to get started. Non-secret configuration lives in config.yaml.

Authentication & Roles

Meerkat uses OpenID Connect (OIDC) for authentication. All routes require authentication except /docs, /openapi.yaml, and /metrics.

Roles

The ADMIN_USERS variable accepts a comma-separated list of OIDC preferred_username values (case-insensitive). Users whose username matches an entry are assigned the admin role; all others get reader. If ADMIN_USERS is unset, all authenticated users are treated as admins.

ADMIN_USERS=jalexander,jdoe

CI Agent — Setup

The Meerkat CI agent is a single static Go binary distributed as a container image (meerkat-ci-agent:latest). Add the following stage to any project's .ci-pipeline.yml:

meerkat-scan:
  stage: test
  image: registry.internal/internal/meerkat-ci-agent:latest
  variables:
    MEERKAT_URL: "https://meerkat.internal"
    MEERKAT_SECRET: $MEERKAT_WEBHOOK_SECRET
  script:
    - meerkat-ci-agent --output meerkat-report.json
  artifacts:
    paths:
      - meerkat-report.json
    when: always
    expire_in: 30 days
  allow_failure: false

CI_PROJECT_ID is provided automatically by your CI platform — no extra configuration needed.

CI Agent Environment Variables

CI Agent — Flags & Exit Codes

Flags

Exit Codes

CI Agent — Artifact Output

When --output is specified, the agent writes a JSON file wrapping the scan response with CI metadata:

{
  "http_status": 200,
  "timestamp": "2026-04-09T11:00:00Z",
  "ci_project_id": "42",
  "ci_pipeline_id": "12345",
  "ci_job_id": "67890",
  "result": {
    "status": "pass",
    "project_id": 1,
    "project_name": "my-app",
    "violations": [],
    "violation_count": 0,
    "allow_list_violations": [],
    "allow_list_violation_count": 0,
    "allow_list_enforced": false,
    "scan_status": "success",
    "dependency_count": 87,
    "message": "Scan completed. No policy violations found."
  }
}

Supported Package Ecosystems

Meerkat extracts dependencies from the following manifest file types:

API Reference

All endpoints are under /api/v1/. Full interactive documentation is available at /docs (Swagger UI) and the raw schema at /openapi.yaml.