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/probelabs/goreplay 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.

WAIT — Slowing — last commit 3mo ago

• Last commit 3mo ago
• 21+ active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 3mo ago
• ⚠ Concentrated ownership — top contributor handles 51% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{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 probelabs/goreplay repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/probelabs/goreplay.

What it runs against: a local clone of probelabs/goreplay — 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 probelabs/goreplay | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 132 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of probelabs/goreplay. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/probelabs/goreplay.git
#   cd goreplay
#
# 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 probelabs/goreplay and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "cmd/gor/gor.go" \\
  && ok "cmd/gor/gor.go" \\
  || miss "missing critical file: cmd/gor/gor.go"
test -f "emitter.go" \\
  && ok "emitter.go" \\
  || miss "missing critical file: emitter.go"
test -f "input_raw.go" \\
  && ok "input_raw.go" \\
  || miss "missing critical file: input_raw.go"
test -f "input_http.go" \\
  && ok "input_http.go" \\
  || miss "missing critical file: input_http.go"
test -f "internal/capture/capture.go" \\
  && ok "internal/capture/capture.go" \\
  || miss "missing critical file: internal/capture/capture.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 132 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~102d)"
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/probelabs/goreplay"
  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).

GoReplay is an open-source network traffic capture and replay tool written in Go that records live HTTP traffic from production without modifying infrastructure, then replays it to test environments for shadowing, load testing, and system validation. It uses packet-level sniffing (via gopacket) to transparently intercept traffic and forward it to test targets, eliminating the need for proxy changes in production. Monolithic single-binary architecture: cmd/gor/gor.go is the main entry point wrapping core traffic capture logic, ce.go handles commercial edition features, with modular input/output plugins architecture (referenced via --input-raw, --output-http, --output-stdout flags). Traffic flows: raw packet capture → format parsing → filtering/rewriting → output handlers. Documentation is wiki-style in /docs/ with feature-focused guides (Capturing-and-replaying-traffic.md, Request-filtering.md, etc).

DevOps engineers, SREs, and QA teams who need to continuously test staging/test environments with real production traffic patterns without deploying proxies or modifying production infrastructure. Platform engineers building CI/CD pipelines that require realistic load testing and traffic analysis.

Production-ready and actively maintained. The project has CI workflows (ci-test.yaml, ci-docker.yaml), extensive documentation in /docs/, commercial offerings (docs/commercial/), and integration with multiple backends (Kafka via Shopify/sarama, ElasticSearch, Kubernetes). Latest Go version is 1.21, dependencies are recent (aws-sdk-go 1.44.262, google/gopacket maintained fork), though commit recency from the provided data is unclear.

Moderate risk: requires root/elevated privileges to capture raw packets, has 15+ transitive dependencies including outdated ones (google/gopacket is from 2021-04-29), and commercial features suggest potential split between open-source and proprietary code paths. Single primary author (buger) indicates potential bus factor, though community contributions appear active via dependabot and issue tracking.

Active security scanning (Semgrep via .github/workflows/semgrep.yml), Docker builds (ci-docker.yaml), and dependency management (dependabot.yaml). CodeSee architecture diagrams are being generated (codesee-arch-diagram.yml). No specific PR data visible, but the presence of Dockerfile.dev and Procfile suggests active local development support.

Clone and build: git clone https://github.com/buger/goreplay && cd goreplay && make (Makefile exists with 6.5KB of build logic). Minimal test: sudo ./gor --input-raw :8000 --output-stdout (requires root for packet capture). For HTTP replay: sudo ./gor --input-raw :8000 --output-http http://staging.env.

Daily commands: Development: make builds the binary. Run basic capture: sudo ./gor --input-raw :8000 --output-stdout. Run with HTTP replay: sudo ./gor --input-raw :8000 --output-http http://test-env:8000. Docker: docker build -f Dockerfile -t goreplay . && docker run --net=host goreplay (Dockerfile exists for containerization).

• cmd/gor/gor.go — Main entry point and CLI argument parsing; required to understand how the tool initializes, configures inputs/outputs, and orchestrates traffic capture/replay.
• emitter.go — Core message/event loop dispatcher that routes captured or replayed traffic between inputs and outputs; fundamental to the request-response pipeline.
• input_raw.go — Implements live packet capture from network interfaces using libpcap; essential for understanding how GoReplay intercepts real HTTP traffic.
• input_http.go — HTTP client for replaying captured traffic to target systems; critical for the replay-side of the traffic shadowing feature.
• internal/capture/capture.go — Abstracts packet capture operations across platforms (Linux AF_PACKET, others via libpcap); load-bearing for network portability.
• http_modifier.go — Implements request/response filtering and rewriting middleware; key extension point for traffic transformation logic.
• go.mod — Declares all dependencies including sarama (Kafka), elastigo (Elasticsearch), and gopacket; critical for build reproducibility.

Add a new input source (e.g., message queue, socket, file format)

1. Create a new file input_<source>.go implementing the input interface similar to input_raw.go or input_kafka.go (input_<source>.go)
2. Implement required methods: PluginRead(), PluginWrite(), and Close() to emit messages into the emitter (input_<source>.go)
3. Register the input plugin in the main CLI dispatcher by adding a case in cmd/gor/gor.go to instantiate it based on flags (cmd/gor/gor.go)
4. Add unit tests in input_<source>_test.go following the pattern of input_file_test.go or input_kafka_test.go (input_<source>_test.go)

Add HTTP request/response filtering or rewriting rules

1. Define new rule types or conditions in http_modifier_settings.go by extending the settings struct (http_modifier_settings.go)
2. Implement the matching and transformation logic in http_modifier.go by adding functions that parse and apply rules to requests/responses (http_modifier.go)
3. Add tests in http_modifier_test.go to verify rule matching and transformation behavior (http_modifier_test.go)
4. Expose the new settings flags in cmd/gor/gor.go so users can enable and configure rules via CLI (cmd/gor/gor.go)

Support a new export destination (e.g., database, custom endpoint, S3)

1. Create a new file output_<destination>.go similar to elasticsearch.go that implements writing captured traffic (output_<destination>.go)
2. Implement the plugin interface methods PluginWrite() and Close() to batch and send messages to the destination (output_<destination>.go)
3. Register the output in cmd/gor/gor.go so it can be selected via CLI flags (cmd/gor/gor.go)
4. Add integration tests in output_<destination>_test.go to verify connectivity and message delivery (output_<destination>_test.go)

Add platform-specific packet capture optimization

1. Create a new capture backend file in internal/capture/capture_<platform>.go (e.g., capture_windows.go) (internal/capture/capture_<platform>.go)
2. Implement platform-specific packet interception using native APIs (WinPcap, pfring, etc.) following the interface in internal/capture/capture.go (internal/capture/capture_<platform>.go)
3. Add conditional build tags and compilation logic in the Makefile to enable the new platform (Makefile)
4. Update internal/capture/doc.go with documentation for the new platform support (internal/capture/doc.go)

• gopacket (libpcap wrapper) — Provides cross-platform packet capture and TCP/HTTP parsing; abstracts OS-specific APIs (AF_PACKET on Linux, WinPcap on Windows).
• AF_PACKET (Linux) — Kernel-level packet capture with zero-copy ring buffers for ultra-low latency and high throughput on Linux systems.
• Elasticsearch (mattbaird/elastigo) — Enables scalable, full-text searchable archival and analysis of traffic patterns across distributed deployments.
• Kafka (Shopify/sarama) — Decouples traffic capture from replay/analysis, enabling horizontal scaling and durability across multiple GoReplay instances.
• Kubernetes client-go — Allows GoReplay to run in Kubernetes clusters and auto-discover services/endpoints for dynamic traffic shadowing.

• Packet-level capture via libpcap vs. HTTP-level proxying

  • Why: Packet capture is non-intrusive (no code changes to applications) but requires root/CAP_NET_ADMIN; HTTP proxying requires app integration but avoids privilege escalation.
  • Consequence: GoReplay sacrifices ease of deployment (requires elevated privileges) for zero application changes and transparent traffic interception.

• In-memory ring buffers + optional Kafka/Elasticsearch export

  • Why: Local buffering minimizes latency for shadowing; Kafka/Elasticsearch enable distributed persistence but add operational complexity.
  • Consequence: Small-scale deployments can capture/replay locally; large-scale deployments must configure external systems or risk traffic loss under high throughput.

• Stateless message processing (no session correlation)

  • Why: Simplifies architecture and scales horizontally; each message processed independently.
  • Consequence: Cannot replay complex multi-request flows requiring session state (e.g., login → authenticated request); suitable for load testing but not full integration testing.

• HTTP request/response filtering via regex and header matching

  • Why: Simple, declarative rules avoid runtime overhead and don't require middleware binaries.
  • Consequence: Cannot perform complex transformations (e.

Root requirement: all traffic capture (--input-raw) requires root/CAP_NET_ADMIN privilege—development on non-Linux or unprivileged environments is problematic. BPF/libpcap dependency: gopacket depends on system libpcap/WinPcap libraries not listed in go.mod; compilation may fail without OS-level packet capture libraries installed. Kubernetes integration: k8s.io/client-go v0.27.1 is included but usage pattern is undocumented; unclear if required for all deploys or only distributed mode. gopacket fork version: uses 2021-04 fork (1.1.20-0.20210429153827) which is stale; newer google/gopacket versions may have incompatible APIs. Commercial vs open-source code paths: ce.go suggests feature gating; some flags may behave differently if licensing check fails. gorilla/websocket v1.5.0: included but WebSocket use cases are not documented in main README.

• Packet-level traffic capture (libpcap/BPF) — GoReplay's core capability relies on Berkeley Packet Filter to intercept raw TCP/IP packets without modifying application code or inserting proxies; essential to understand for debugging capture failures
• HTTP message parsing from raw packets — Reconstructing HTTP requests/responses from fragmented TCP packets is non-trivial; GoReplay must handle reassembly, chunked encoding, and connection state—critical for understanding output accuracy
• Traffic shadowing / mirroring patterns — GoReplay implements production traffic shadowing (sending copies to test env) vs inline proxying; understanding this pattern explains why it's safe for production use
• Request/response filtering and rewriting middleware — Middleware chains allow selective capture and mutation of traffic (headers, paths, auth tokens); core feature for avoiding sensitive data leakage in test environments
• Rate limiting and adaptive traffic control — GoReplay can replay at different rates than captured (--input-raw :8000 --output-http with rate flags); essential for load testing without overwhelming staging
• Distributed traffic collection and aggregation — Multi-instance GoReplay deployments can feed into centralized Kafka/ElasticSearch; understanding coordinator patterns is needed for large-scale deployments
• TCP connection state tracking — Reconstructing request/response pairs from raw packets requires tracking TCP state machines; essential for understanding why some traffic is dropped or malformed

• buger/gor-openapi — Companion project for generating OpenAPI specs from captured traffic, extends GoReplay's analysis capabilities
• cloud/goproxy — Alternative HTTP-level traffic capture using Go's built-in HTTP server, less efficient than packet-level but no root required
• eycorsican/Gor — Another traffic replay tool with similar shadowing approach but written in different language; useful for understanding design trade-offs
• google/gapid — Google's graphics API debugger that uses similar packet-interception patterns for graphics pipeline replay; relevant for understanding packet capture state machine design
• mitmproxy/mitmproxy — Complimentary proxy-based traffic inspection tool; GoReplay is non-intrusive alternative for production use where mitmproxy would require infrastructure changes

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 comprehensive unit tests for elasticsearch.go and elasticsearch_test.go

The elasticsearch.go file handles critical ElasticSearch integration, but elasticsearch_test.go appears minimal based on the file structure. Given that ELASTICSEARCH.md exists as documentation, there's clearly active ElasticSearch functionality that needs better test coverage. This would improve reliability for users exporting traffic data to ElasticSearch and catch regressions early.

• [ ] Review existing elasticsearch_test.go to identify gaps in test coverage
• [ ] Add unit tests for ElasticSearch connection handling and error cases
• [ ] Add tests for request marshalling/unmarshalling to ElasticSearch format
• [ ] Add integration test examples using testcontainers or mock ElasticSearch
• [ ] Ensure tests cover the actual use cases documented in ELASTICSEARCH.md

Add GitHub Actions workflow for building and testing multiple Go versions

The project specifies go 1.21 in go.mod but only has ci-test.yaml workflow. There's no visible multi-version Go testing (e.g., 1.20, 1.21, 1.22), which is critical for a library used by others. This would catch compatibility issues early and ensure the project doesn't accidentally use 1.21-specific features that break older versions.

• [ ] Create .github/workflows/ci-go-versions.yaml
• [ ] Configure matrix strategy to test against go 1.20, 1.21, and 1.22
• [ ] Ensure it runs on push and pull_request events
• [ ] Test both linux/amd64 and linux/arm64 if applicable (see Dockerfile)
• [ ] Link the new workflow results to README.md

Add missing unit tests for emitter.go functionality

emitter.go and emitter_test.go exist in the codebase, suggesting the emitter is a core component for event distribution during traffic capture/replay. The test file likely has incomplete coverage given the complexity of event handling. Adding comprehensive tests here would improve reliability of the core message passing system.

• [ ] Review emitter_test.go to identify missing test cases
• [ ] Add tests for concurrent event emission and listener management
• [ ] Add tests for edge cases (nil listeners, removed listeners during emission)
• [ ] Add benchmarks for event emission performance
• [ ] Verify tests cover both the capture pipeline and replay pipeline using the emitter

• Add integration tests for the three primary output backends (HTTP, Kafka, ElasticSearch). Currently no test files visible for output plugin implementations—write integration tests against docker-compose services (kafka, elasticsearch) to verify payload transformation and delivery: medium
• Document the middleware/request-rewriting DSL with concrete examples. docs/Middleware.md and docs/Request-filtering.md exist but lack executable example configs and field reference docs—add example YAML configs and inline code samples to docs/getting-started/: small
• Add distributed mode examples to docs/Distributed-configuration.md with K8s manifests and docker-compose.yml. k8s.io/client-go is in dependencies but no example deployments are visible—create manifests/ directory with StatefulSet + ConfigMap examples for multi-node traffic collection: medium

• High · Outdated Go Version — go.mod. The project targets Go 1.21, which is no longer the latest stable version. Security patches and bug fixes from newer versions are not available. Go 1.21 reached end-of-life in August 2024. Fix: Update to the latest stable Go version (1.23+) to receive security updates and patches.
• High · Vulnerable Dependency: google/gopacket — go.mod (google/gopacket v1.1.20-0.20210429153827-3eaba0894325). The dependency 'github.com/google/gopacket' is pinned to a pre-release version (v1.1.20-0.20210429153827-3eaba0894325) from April 2021. This is significantly outdated and may contain known security vulnerabilities in packet parsing. Fix: Update to the latest stable version of google/gopacket. Use 'go get -u github.com/google/gopacket' to fetch the latest secure version.
• High · Vulnerable Dependency: mattbaird/elastigo — go.mod (mattbaird/elastigo v0.0.0-20170123220020-2fe47fd29e4b). The 'github.com/mattbaird/elastigo' dependency is pinned to a version from 2017 (v0.0.0-20170123220020-2fe47fd29e4b). This package is extremely outdated and likely contains multiple known vulnerabilities. The package appears to be unmaintained. Fix: Replace with an actively maintained Elasticsearch client library such as 'github.com/elastic/go-elasticsearch' or 'github.com/olivere/elastic'. The current package is deprecated and unsupported.
• High · Vulnerable Dependency: Shopify/sarama — go.mod (Shopify/sarama v1.38.1). The Shopify/sarama dependency (v1.38.1) is outdated. There are known security vulnerabilities in Kafka client libraries. This version was released in 2023 and newer patches exist. Fix: Update to the latest version of Shopify/sarama using 'go get -u github.com/Shopify/sarama'. Review the changelog for security fixes.
• Medium · Vulnerable Dependency: aws/aws-sdk-go — go.mod (aws/aws-sdk-go v1.44.262). The AWS SDK for Go (v1.44.262) is the older v1 version. AWS has released v2 with improved security features and better dependency management. V1 may have known vulnerabilities that are only fixed in v2. Fix: Migrate to AWS SDK for Go v2 (github.com/aws/aws-sdk-go-v2). This version provides better security practices and is actively maintained.
• Medium · Insecure Docker Base Image — Dockerfile (FROM alpine:3.16). The Dockerfile uses 'alpine:3.16' which is outdated (released in 2022). Alpine 3.16 is no longer receiving security updates. Newer versions include critical security patches. Fix: Update to a newer Alpine version such as 'alpine:3.20' or 'alpine:latest' to ensure all base system packages include the latest security patches.
• Medium · Binary Download from GitHub Without Verification — Dockerfile (wget https://github.com/buger/goreplay/releases/download/...). The Dockerfile downloads a pre-built binary from GitHub releases without verifying its integrity using checksums or signatures. This could allow for man-in-the-middle attacks or compromised binaries. Fix: Implement binary verification: download checksums/signatures alongside the binary, verify authenticity using GPG or SHA256 checksums before extracting and running the binary.
• Medium · Missing Security Headers in Documentation — docs/ directory (especially Capturing-and-replaying-traffic.md). The codebase includes network monitoring and HTTP traffic replay capabilities. The documentation does not clearly address security considerations for sensitive data handling, SSL/TLS validation, or credential transmission. Fix: Add security guidelines documentation covering: handling of

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.