If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/keploy/keploy shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 13 active contributors
• Distributed ownership (top contributor 39% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live keploy/keploy repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/keploy/keploy.

What it runs against: a local clone of keploy/keploy — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in keploy/keploy | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of keploy/keploy. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/keploy/keploy.git
#   cd keploy
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of keploy/keploy and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "keploy/keploy(\\.git)?\\b" \\
  && ok "origin remote is keploy/keploy" \\
  || miss "origin remote is not keploy/keploy (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/keploy/keploy"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Keploy is an open-source API and integration testing platform that auto-generates tests and data mocks by recording real API calls, database queries, and streaming events at the network layer using eBPF, then replaying them as reproducible tests. It eliminates the need for manual test case writing by capturing production traffic and converting it into executable test suites with 90%+ coverage in minutes. Monorepo structure: CLI entry points in root, agent component for network interception (eBPF-based), with GitHub workflows in .github/workflows/ for multi-platform builds (Linux/macOS/Windows). Skills/documentation under .claude/skills/ suggest AI-assisted docs; Dockerfiles and shell scripts handle containerized testing. CI uses matrix builds for Go testing (go-test.yaml, golang_docker.yml) with separate macOS/Windows variants.

Backend and full-stack developers building APIs who need rapid test coverage without writing boilerplate test code; QA engineers automating integration testing across multiple services; teams adopting AI-driven testing in CI/CD pipelines who want safe, isolated production sandboxes.

Production-ready and actively maintained. The codebase shows 3.9M+ lines of Go, comprehensive CI workflows (20+ GitHub Actions including coverage, CodeQL, e2e tests across Linux/macOS/Windows), and a CNCF Landscape listing. The monorepo structure with CLI, agent, and UI components, plus badge integration with Coveralls, indicates mature tooling; active Slack/YouTube communities suggest ongoing development.

Low-to-moderate risk: eBPF dependency introduces kernel-version constraints (Linux 4.18+); single primary language (Go) reduces fragmentation but concentrates expertise. No visible dependency audit in file list, though pinned Flask/Gunicorn versions suggest careful management. The complexity of network-layer traffic capture could introduce subtle platform-specific bugs; Windows CI exists but eBPF is Linux-native.

Active feature development: E2E test workflows (e2e-agent-ready-ca-gate.yml, e2e-ca-bundle-merge.yml) indicate work on certificate handling and agent readiness gates. Fuzzing infrastructure (fuzzer_linux.yml) suggests security hardening. PR workflow automation (.claude/skills/keploy-pr-workflow) and docs automation point to tooling improvements. Windows support being expanded (golang_docker_windows.yml, cleanup scripts).

Clone and build: git clone https://github.com/keploy/keploy && cd keploy && go build -o keploy ./cmd/keploy. For testing: go test ./.... For Docker: docker build -f Dockerfile -t keploy:latest .. See .github/workflows/golang_linux.yml for exact build matrix commands.

Daily commands: Development: go run ./cmd/keploy record to capture traffic, go run ./cmd/keploy test to replay. For Docker development: build image with docker build -f Dockerfile ., then run container-based tests. Use go test ./... for unit tests. CI runs via make test (inferred from workflow patterns); exact Makefile commands visible in .github/workflows/.

• .github/workflows/golang_linux.yml: Defines the core Linux build and test matrix for Go; the primary CI pipeline for this Go-heavy project
• .github/workflows/go-test.yaml: Runs unit tests and generates coverage reports; critical for validating changes across the codebase
• .github/workflows/codeql.yml: CodeQL security analysis; indicates security-first development posture for a tool that intercepts network traffic
• Dockerfile: Containerization for the tool; essential for reproducible, isolated test sandboxes (core product feature)
• .github/scripts/windows/ensure-docker.ps1: Windows CI setup; critical for multi-platform support parity
• .github/CODEOWNERS: Defines code review authority; essential for understanding governance and who to ask for guidance
• .cz.toml: Commitizen config for conventional commits; enforces structured changelog generation

New CLI commands: add Go files under cmd/keploy/ (entry point). eBPF/capture logic: modify agent components (path inferred as pkg/agent/ or similar for network interception). Test replay engine: likely in pkg/test/ or internal/replay/. Documentation: add .md files and update .claude/skills/keploy-docs/SKILL.md. CI workflows: edit files in .github/workflows/. Windows support: scripts in .github/scripts/windows/ for platform-specific setup.

eBPF kernel requirement: Must run on Linux 4.18+ or macOS 13+ (native) or Windows via WSL2 — eBPF failures on older kernels are silent without proper error messages. Agent daemon: Likely requires elevated privileges (root/CAP_SYS_RESOURCE) to attach eBPF probes; non-obvious permission errors in production sandboxes. Docker-in-Docker: Windows CI scripts reference Docker setup; nested containerization can fail silently. Certificate handling: Recent e2e-ca-bundle-merge.yml suggests CA cert injection complexity when recording HTTPS traffic. Go module versions: Flask/Gunicorn pinning in dependencies suggests external service test fragility; breaking dependency updates require explicit test pins. GitHub Actions setup: Custom actions in .github/actions/ (download-binary, download-image, setup-private-parsers) must be available; private parser setup may require repo secrets not visible here.

• eBPF (extended Berkeley Packet Filter) — Core technology enabling Keploy to intercept network traffic at kernel level without code instrumentation; understanding eBPF syscall hooks is critical for debugging capture failures and platform limitations
• Record-Replay Testing — The fundamental pattern of Keploy: capture real interactions, deterministically replay them; essential for understanding test flakiness, timing issues, and why mocking works
• Network Syscall Interception — Keploy uses eBPF to hook socket syscalls (sendto, recvfrom, etc.) to capture traffic; knowledge of Linux syscall ABI helps debug packet loss, ordering issues, and protocol edge cases
• Production Sandbox Isolation — Keploy's promise is safe, isolated testing of production traffic; understanding container namespaces, cgroups, and network isolation is crucial for preventing sandbox escape and data leakage
• gRPC and Protocol Buffers — The distributed agent-CLI architecture almost certainly uses gRPC for communication; understanding message serialization and bidirectional streaming is key for agent debugging and extending CLI features
• Conventional Commits (Commitizen) — Repo enforces structured commit messages (.cz.toml); required for changelog automation and CI workflows; violating this breaks release pipelines
• Matrix CI/CD Builds — Keploy CI uses Go matrix builds across Linux/macOS/Windows with different architectures; understanding matrix expansion is essential for adding new platforms or fixing platform-specific bugs

• grafana/xk6-http — Similar traffic capture + replay approach for HTTP load testing; alternative architecture for distributed request mocking
• pact-foundation/pact-go — Consumer-driven contract testing alternative; overlaps on API mock generation but focuses on bilateral contract validation vs. passive recording
• mockoon/mockoon — Manual API mock server; complements Keploy's auto-generation by providing fallback UI for editing captured mocks
• getporter/porter — CNCF companion tool for bundle automation; relevant for Keploy's sandbox environment orchestration in CI/CD
• kubernetes/kubernetes — Keploy sandboxes often run on Kubernetes; understanding K8s network policies and isolation is essential for production use

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Windows-specific E2E tests in CI workflow

The repo has extensive Windows support scripts (.github/scripts/windows/) and multiple Windows workflows (go_windows.yml, golang_native_windows.yml, golang_wsl.yml), but no dedicated E2E test workflow for Windows. Given that .github/workflows/e2e-agent-ready-ca-gate.yml and e2e-ca-bundle-merge.yml exist only for Linux/macOS, Windows E2E coverage is a gap. This is critical for a tool that claims cross-platform production sandbox testing.

• [ ] Review .github/workflows/e2e-agent-ready-ca-gate.yml and .github/workflows/e2e-ca-bundle-merge.yml to understand current E2E test structure
• [ ] Examine .github/scripts/windows/ (cleanup-windows.ps1, ensure-docker.ps1, setup-git-isolation.ps1) to identify Windows-specific setup needs
• [ ] Create .github/workflows/e2e-windows.yml that mirrors E2E tests but uses Windows runners and PowerShell scripts
• [ ] Ensure the workflow handles Docker isolation and Git isolation on Windows as defined in existing scripts

Add integration tests for Python/Node/Java language-specific recording features

The repo has language-specific CI workflows (python_linux.yml, node_linux.yml, java_linux.yml, python_docker.yml, node_docker.yml) but the corresponding integration test coverage is unclear. The .claude/skills/keploy-e2e-test/SKILL.md file exists but there's no dedicated integration test directory structure visible. New contributors could add comprehensive integration tests for each supported language's recording/playback cycle.

• [ ] Review .claude/skills/keploy-e2e-test/SKILL.md to understand the E2E testing skill structure
• [ ] Create integration test suite for Python using Flask + gunicorn (versions pinned in Dependencies) in a new tests/integration/python/ directory
• [ ] Create integration test suite for Node in tests/integration/node/ covering a sample Express/HTTP server
• [ ] Create integration test suite for Java in tests/integration/java/ with a sample Spring Boot or similar application, matching workflow triggers in .github/workflows/java_linux.yml

Document CI workflow matrix and add coverage matrix visualization

The repo has 30+ workflows across different languages, Docker variants, and OS platforms (Linux, macOS, Windows, WSL), but .github/CI_CONTRIBUTING.md likely lacks clear documentation on which workflows test what. New contributors struggle to understand why so many similar workflows exist. Adding a structured matrix documentation and a workflow dependency graph would reduce confusion.

• [ ] Audit all .github/workflows/*.yml files and categorize them by: language (Go/Python/Node/Java), environment (Docker/native), OS (Linux/macOS/Windows), and purpose (unit tests/E2E/lint/security)
• [ ] Create or enhance .github/CI_CONTRIBUTING.md with a clear matrix table showing workflow triggers, supported languages, and expected outcomes
• [ ] Add inline comments to 5-10 of the most complex/similar workflows (e.g., golang_docker.yml vs golang_docker_macos.yml vs golang_docker_windows.yml) explaining the differences and why duplication exists
• [ ] Reference the matrix in .github/CONTRIBUTING.md for new contributors choosing which workflows to modify

• Add Windows native eBPF support tests: The .github/scripts/windows/ folder has setup scripts but fuzzer_linux.yml and eBPF references suggest Windows eBPF testing is incomplete. A junior could implement platform-specific test guards in go-test.yaml to skip eBPF tests on Windows CI and add a tracking issue.
• Document the agent-CLI gRPC contract: No visible .proto files in the file list despite distributed agent architecture. A junior could extract the gRPC service definitions (likely in pkg/agent/ or internal/rpc/), generate .proto documentation, and add it to .claude/skills/keploy-docs/SKILL.md.
• Expand CodeQL ruleset for network interception code: codeql-config.yml exists but likely needs tuning for eBPF-specific CVEs (buffer overflows, privilege escalation). A junior could propose additional queries in a small PR against .github/codeql/codeql-config.yml with links to relevant CWE/CVE examples.

The Keploy codebase demonstrates moderate security posture with established

• High · Insecure Gunicorn Version Pin — dependencies/Package file (gunicorn==25.3.0). Gunicorn is pinned to version 25.3.0, which may contain known vulnerabilities. The comment indicates this version was chosen to match a specific customer environment for bug reproduction, but this creates a security liability by intentionally using a potentially outdated version in production contexts. Fix: Update to the latest stable version of Gunicorn (>=27.0 as of 2024). If version 25.3.0 is required for testing specific bugs, isolate this to a separate test environment and document the security implications. Consider using security scanning tools like pip-audit or Safety to identify known CVEs.
• Medium · Flask Version Specificity — dependencies/Package file (flask==3.0.3). Flask is pinned to version 3.0.3. While pinning versions is generally good practice, ensure this version is regularly audited for security updates. Flask 3.0.3 is relatively recent, but without a process to monitor and update dependencies, security patches may be missed. Fix: Implement automated dependency vulnerability scanning in CI/CD pipeline (e.g., Dependabot, Snyk, or OWASP Dependency-Check). Establish a policy for regular dependency updates, at least quarterly.
• Medium · Missing Security Headers Configuration — Flask application configuration (not visible in provided files). No visible security headers configuration (CSP, HSTS, X-Frame-Options, etc.) in the Flask/Gunicorn setup. This could expose the application to XSS, clickjacking, and other web-based attacks. Fix: Implement security headers middleware in Flask application. Add Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and HSTS headers to all responses.
• Medium · Insecure Dependency Sourcing — dependencies/Package file. Dependencies are pinned without hash verification. No evidence of lock files or hash-based verification (e.g., pip-compile with hashes or requirements.txt with --hash flag) which could allow man-in-the-middle attacks during dependency installation. Fix: Use pip-compile with --generate-hashes or implement package signature verification. Consider using a private package index with integrity checks. Document the dependency management process.
• Low · Missing SECURITY.md Best Practices — .github/SECURITY.md. While SECURITY.md exists with a vulnerability reporting process, it lacks specific guidance on: SLA for vulnerability response, security update policy, supported versions, and deprecation timeline. The contact email 'hello@keploy.io' is generic. Fix: Enhance SECURITY.md with: (1) Expected response time for vulnerability reports, (2) Supported versions and security patch timelines, (3) Disclosure policy (coordinated vs. full disclosure), (4) Dedicated security contact email, (5) PGP key for encrypted communications if applicable.
• Low · Dockerfile CGO Configuration — Dockerfile (referenced in Docker security context). The Dockerfile explicitly sets CGO_ENABLED=1 for libpg_query compatibility. While documented, CGO introduces compilation complexity and potential for C library vulnerabilities. The reliance on external C libraries (libpg_query) increases supply chain risk. Fix: Maintain updated base image (golang:1.26 on Debian bookworm). Regularly audit libpg_query for vulnerabilities. Consider implementing SBOM (Software Bill of Materials) generation for supply chain transparency. Use multi-stage builds to minimize final image size and attack surface.
• Low · No Visible Static Analysis Configuration — .github/workflows (CodeQL present, but pre-commit hooks not visible). While CodeQL workflow exists, there's no visible evidence of Go-specific static analysis tools (gosec, staticcheck) or Python security scanners (bandit) being enforced at commit time. Security scanning appears to run post-commit only. Fix: Implement pre-commit hooks with gosec for Go code and bandit for Python code. Add go vet, go fmt, and golangci-lint to CI/CD as blocking checks. Enforce CodeQL on pull requests with required reviews.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.