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/tylertreat/comcast 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 — Stale — last commit 1y ago

• 27+ active contributors
• Apache-2.0 licensed
• CI configured
• ⚠ Stale — last commit 1y ago
• ⚠ Concentrated ownership — top contributor handles 51% of recent commits
• ⚠ No test directory detected

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

What it runs against: a local clone of tylertreat/comcast — 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 tylertreat/comcast | 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 master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 443 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tylertreat/comcast(\\.git)?\\b" \\
  && ok "origin remote is tylertreat/comcast" \\
  || miss "origin remote is not tylertreat/comcast (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "comcast.go" \\
  && ok "comcast.go" \\
  || miss "missing critical file: comcast.go"
test -f "throttler/throttler.go" \\
  && ok "throttler/throttler.go" \\
  || miss "missing critical file: throttler/throttler.go"
test -f "throttler/tc.go" \\
  && ok "throttler/tc.go" \\
  || miss "missing critical file: throttler/tc.go"
test -f "throttler/pfctl.go" \\
  && ok "throttler/pfctl.go" \\
  || miss "missing critical file: throttler/pfctl.go"
test -f "throttler/ipfw.go" \\
  && ok "throttler/ipfw.go" \\
  || miss "missing critical file: throttler/ipfw.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 443 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~413d)"
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/tylertreat/comcast"
  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).

Comcast is a CLI tool that simulates degraded network conditions (latency, bandwidth throttling, packet loss, reordering, corruption) by wrapping platform-specific network control utilities. On Linux it uses iptables and tc (traffic control), on macOS/BSD it uses pfctl or ipfw. It lets you test distributed systems under realistic poor-network scenarios without requiring actual network failure. Monolithic Go binary with a throttler package abstraction layer: comcast.go is the CLI entry point, throttler/throttler.go defines the Throttler interface, and platform-specific implementations (tc.go for Linux, pfctl.go and ipfw.go for macOS/BSD) wrap system binaries. No separate cmd/ or internal/ structure—direct strategy pattern in throttler/.

Backend engineers and SREs building distributed systems who need to test resilience under degraded network conditions (high latency, limited bandwidth, packet loss) before deploying to production. Also useful for chaos engineering practitioners validating system behavior under partial failures.

Moderately mature but showing signs of age: single maintainer (tylertreat), no visible recent commits in the repo data, no test files for the main comcast.go entry point, minimal CI setup (only .travis.yml), and Go 1.15 is several versions old. Production-usable for specific platforms (Linux/macOS) but not actively maintained.

Low dependency risk (only imports github.com/tylertreat/comcast itself per go.mod), but single-maintainer maintenance risk is high with no recent activity visible. Platform-specific code paths (throttler/tc.go, throttler/pfctl.go, throttler/ipfw.go) could silently break with OS updates. No test coverage for main entry point (comcast.go) means regressions may not be caught.

No visible activity in the provided repo data. No recent commits, open PRs, or milestones are indicated. The project appears to be in maintenance mode or dormant.

go install github.com/tylertreat/comcast@latest
export PATH=$PATH:$HOME/go/bin
comcast --help

Daily commands: Requires root: sudo comcast --device=eth0 --latency=250 --target-bw=1000 --packet-loss=10%. Use --dry-run to preview commands without execution. Use comcast --stop to remove throttling.

• comcast.go — Main entry point and CLI handler that orchestrates throttler selection and network failure injection across all platforms.
• throttler/throttler.go — Core abstraction defining the Throttler interface that all platform-specific implementations must satisfy.
• throttler/tc.go — Linux traffic control implementation using iptables and tc; handles the majority of production deployments.
• throttler/pfctl.go — BSD/macOS packet filter implementation; critical for developer testing on OSX systems.
• throttler/ipfw.go — Legacy BSD firewall implementation providing fallback network failure injection on older systems.
• go.mod — Module definition; surprisingly lists comcast itself as a dependency, indicating vendoring or internal testing patterns.
• Makefile — Build automation and platform-specific compilation targets for Linux, BSD, and macOS binaries.

• comcast.go (CLI) (Go flag package, os/runtime detection) — Parses command-line arguments (latency, bandwidth, packet loss, reordering, corruption, target interface), detects OS, instantiates appropriate Throttler, invokes Start/Stop.
  • Failure mode: Fails to parse args or detect OS → exits with error; user must re-run with correct flags or on supported system
• Throttler interface (Go interface abstraction) — Abstract contract for platform-specific implementations; defines Start(ip, latency, bandwidth, packetLoss, ...) and Stop() methods.
  • Failure mode: Incomplete implementation → panics at runtime; missing platform support → CLI falls back to error message
• tc.go (Linux implementation) (iptables, tc, qdisc, netfilter) — Constructs iptables rules and tc qdisc commands to apply bandwidth limits, latency, packet loss, reordering, and corruption on Linux.
  • Failure mode: iptables/tc not in PATH → command execution fails; invalid rules → kernel rejects; orphaned rules on crash → must manually flush
• pfctl.go (BSD implementation) (pf) — Generates pfctl anchor/rule syntax to apply packet filtering and dummynet traffic shaping on macOS/BSD.

Add a new network failure mode

1. Add the new parameter to the Throttler interface methods (Start/Stop) in throttler/throttler.go (throttler/throttler.go)
2. Implement the new failure mode for Linux using tc qdisc rules in throttler/tc.go (throttler/tc.go)
3. Implement the new failure mode for pfctl in throttler/pfctl.go using packet filter rules (throttler/pfctl.go)
4. Add ipfw dummynet or pipe rules for legacy BSD support in throttler/ipfw.go (throttler/ipfw.go)
5. Add CLI flags and parsing in comcast.go to expose the new parameter to users (comcast.go)
6. Add test cases in throttler/tc_test.go and throttler/pfctl_test.go to verify correctness (throttler/tc_test.go)

Add support for a new platform/OS

1. Create a new file throttler/<platform>.go implementing the Throttler interface (throttler/throttler.go)
2. Implement Start() method using platform-specific network control APIs (e.g., NetLink for Linux variants, IPFW for Windows) (throttler/<platform>.go)
3. Implement Stop() method to clean up and restore original network state (throttler/<platform>.go)
4. Update comcast.go to auto-detect the platform and select the appropriate throttler implementation (comcast.go)
5. Add build target in Makefile for the new platform's binary (Makefile)

Add targeted traffic filtering by IP/port

1. Extend Throttler interface in throttler/throttler.go to accept optional IP/port filter parameters (throttler/throttler.go)
2. Modify tc.go to use iptables rules that target specific source/destination IPs or ports before applying qdisc (throttler/tc.go)
3. Update pfctl.go to add source/destination filtering rules before packet rate limiting (throttler/pfctl.go)
4. Add CLI flags like --target-ip and --target-port in comcast.go (comcast.go)

• Go — Single compiled binary deployable across Linux and BSD systems without runtime dependencies; suitable for systems-level tooling requiring low overhead.
• iptables + tc (Linux) — De-facto standard for traffic shaping on Linux; provides granular control over qdisc, latency, bandwidth, and packet loss via kernel netfilter and traffic control subsystems.
• pfctl (BSD/macOS) — Native packet filtering framework on OSX/BSD; provides stateful filtering and dummynet integration for traffic shaping without external dependencies.
• ipfw/dummynet (Legacy BSD) — Provides backwards compatibility for older BSD systems before pfctl adoption; implements bandwidth limiting via in-kernel dummynet pipes.

• Single CLI binary wrapping multiple platform-specific implementations

  • Why: Avoid shipping separate tools per OS; unified user interface across Linux, macOS, and BSD.
  • Consequence: Comcast must maintain and test three separate network control implementations; adding new features requires cross-platform effort.

• Direct system tool invocation (tc, iptables, pfctl) rather than netlink/BPF APIs

  • Why: Simpler implementation; reuses well-tested system commands; works across kernel versions.
  • Consequence: Slower startup (fork cost); brittle if system tool behavior changes; less visibility into actual kernel state; harder to debug transient failures.

• No daemon mode; stateful rule management via file-based state or rule patterns

  • Why: Simpler deployment; no background service to manage; rules persist via kernel until explicitly removed.
  • Consequence: Orphaned rules if process crashes; difficult to query current throttling state; no centralized management across multiple Comcast invocations.

• Interface-based abstraction (Throttler) but no plugin system

  • Why: Clean separation between platform logic; allows future extensions.
  • Consequence: New OS support requires code changes and recompilation; cannot be extended at runtime without rebuilding.

• Windows support (acknowledged as possible future work but not currently implemented)
• Persistent rule state management or daemon mode
• Real-time monitoring or metrics export of applied throttling
• GUI or web-based control interface
• User-level traffic shaping (requires root/CAP_SYS_ADMIN on Linux, admin on macOS)

Requires root/sudo to execute (kernel-level network control). Platform detection is implicit (code assumes uname output); no explicit runtime checks. pfctl requires Yosemite+ on macOS; older systems fall back to ipfw silently. iptables/tc on Linux require kernel modules (netfilter, qdisc) to be loaded. The tool directly executes shell commands via os.Cmd—typos or malformed args could accidentally flush all firewall rules. No validation that target addresses are valid CIDR blocks or that port ranges are properly formatted before passing to system commands.

• Traffic Control (tc) and qdisc (queueing discipline) — Linux's primary mechanism for bandwidth limiting and latency injection; comcast.throttler/tc.go directly constructs tc commands, so understanding qdisc types (pfifo, tbf, netem) is essential to modify Linux behavior
• netfilter and iptables packet filtering — Used by tc.go to drop/reorder packets on Linux; comcast constructs statistic-mode iptables rules, so understanding match modules (statistic, protocol, port) is needed to extend packet-loss targeting
• pfctl (packet filter) rule syntax — macOS packet filtering engine used by pfctl.go; requires understanding pfctl's unique anchor system and rule ordering for correct throttling behavior
• ipfw (IP firewall) and dummynet — BSD's traffic shaping subsystem (ipfw.go wrapper); dummynet pipes are how latency/bandwidth are applied on older macOS/BSD systems
• Strategy pattern (behavioral design pattern) — Core architecture of comcast: Throttler interface (throttler.go) with multiple platform-specific implementations (tc.go, pfctl.go, ipfw.go) allows runtime selection without code duplication
• CIDR notation and IP address parsing — comcast.go accepts --target-addr=8.8.8.8,10.0.0.0/24 syntax; platform implementations must parse these to construct correct firewall rules, but there's no visible validation before passing to system commands
• Privilege escalation and sudo requirements — comcast requires root to modify kernel network stack; understanding why (netfilter hooks, packet queueing, firewall anchors) helps avoid misuse and security issues

• alexei-led/pumba — Docker-focused chaos engineering tool; similar goal (simulate failures) but for containerized systems instead of raw network interfaces
• grpc-ecosystem/grpc-java — Includes built-in latency/packet-loss simulation; lets you test gRPC resilience without comcast if your stack is Java/gRPC
• Netflix/chaosmonkey — Higher-level chaos engineering framework; often used in conjunction with network-level tools like comcast to test full failure scenarios
• tc-cli/tc — Direct wrapper around Linux tc (traffic control); alternative if you want to avoid the Go binary and script tc directly
• gremlin/gremlin-python — Commercial chaos engineering platform with built-in network failure scenarios; enterprise alternative if you need managed, multi-tool orchestration

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 unit tests for throttler/ipfw.go

The throttler package has tests for pfctl_test.go and tc_test.go, but ipfw.go (used on BSD/OSX systems) lacks corresponding tests. This is a critical gap since ipfw is a primary control mechanism on macOS. Adding tests would ensure the ipfw implementation works correctly and prevent regressions.

• [ ] Create throttler/ipfw_test.go with test cases for rule parsing and application
• [ ] Mock system calls to ipfw command (similar to existing pfctl_test.go patterns)
• [ ] Test edge cases like invalid rule formats and command failures
• [ ] Verify test coverage matches the complexity of ipfw.go implementation

Add GitHub Actions CI workflow for multi-OS testing

The repo has .travis.yml (legacy CI) but no modern GitHub Actions workflow. Comcast supports Linux (tc/iptables), macOS (ipfw/pfctl), and potentially other Unix systems. A GitHub Actions matrix workflow would test across multiple OS environments (Ubuntu, macOS) and Go versions, ensuring cross-platform compatibility.

• [ ] Create .github/workflows/test.yml with matrix strategy for Linux and macOS runners
• [ ] Test against multiple Go versions (1.15+) to verify compatibility
• [ ] Include linting (golangci-lint) and build verification steps
• [ ] Ensure tests run with appropriate permissions for network manipulation tools

Add integration tests for comcast.go with realistic network scenarios

While unit tests exist for individual throttler backends, comcast.go (the main entry point) lacks integration tests demonstrating real usage patterns. Adding tests that verify end-to-end functionality (e.g., applying latency, bandwidth limits, and packet loss together) would validate the tool works as documented in the README.

• [ ] Create integration test file (e.g., comcast_integration_test.go or tests/ subdirectory)
• [ ] Test main throttling scenarios mentioned in README: latency, bandwidth, dropped/reordered packets
• [ ] Use build tags (//go:build integration) to separate from unit tests
• [ ] Include cleanup verification to ensure rules are properly removed after tests

• Add unit tests for comcast.go: currently no test file exists. Write tests for flag parsing logic, especially CIDR address validation and port range parsing (e.g., --target-port=1000:2000).
• Add integration tests for throttler/tc_test.go and throttler/pfctl_test.go: files exist but are likely minimal. Add tests that mock tc/iptables/pfctl commands to verify correct command construction for edge cases (zero latency, 100% packet loss).
• Document Windows support investigation: README mentions 'may be possible with wipfw' but no implementation exists. Research and document blockers or create a stub throttler/wipfw.go with TODO comments for future contributors.

This security analysis reveals critical vulnerabilities in the comcast codebase. The most severe issues are: (1) a circular dependency in go.mod that indicates misconfiguration, (2) high risk of privilege escalation due to system tool wrapping without visible privilege controls, and (3) potential command injection vulnerabilities when invoking system utilities. The tool requires root/administrator privileges to operate but lacks visible input validation, command injection protections, and comprehensive error handling. These vulnerabilities could allow privilege escalation, arbitrary command execution, or system compromise. The c

• High · Circular Dependency in go.mod — go.mod. The go.mod file contains a self-referential dependency: 'require github.com/tylertreat/comcast v1.0.1'. This creates a circular dependency where the module requires itself, which can cause build failures, dependency resolution issues, and is indicative of a misconfiguration that should never exist in a production module. Fix: Remove the self-referential require statement from go.mod. The module should not declare a dependency on itself. Verify the go.mod file is correctly configured and run 'go mod tidy' to clean up dependencies.
• High · Privilege Escalation Risk via System Tool Wrapping — throttler/ipfw.go, throttler/pfctl.go, throttler/tc.go, comcast.go. The tool wraps system-level networking tools (ipfw, pfctl, iptables, tc) that typically require root/administrator privileges. There is no evidence of privilege escalation controls, input validation, or sandboxing in the visible code structure. This could allow privilege escalation if the tool is improperly installed with setuid/setcap bits or run with elevated privileges without proper safeguards. Fix: Implement strict input validation for all command-line arguments before passing to system tools. Document privilege requirements clearly. Avoid setuid/setcap installation. Use principle of least privilege and consider using Go's os/user package to validate execution context. Implement command execution restrictions and whitelisting.
• High · Potential Command Injection via System Tool Invocation — throttler/ipfw.go, throttler/pfctl.go, throttler/tc.go. The tool invokes low-level system utilities (iptables, tc, ipfw, pfctl) based on user input. Without visible evidence of robust input sanitization in the file structure, there is a risk of command injection where specially crafted network parameters could be passed to system commands, potentially allowing arbitrary command execution. Fix: Use Go's exec.Command with argument arrays instead of string concatenation. Never construct shell commands from user input. Implement strict whitelist validation for all network parameters (IP addresses, ports, bandwidth values). Use parameterized approaches where the OS provides them.
• Medium · Missing Input Validation Framework — comcast.go, throttler/throttler.go. No visible validation logic in the file structure for network parameters such as IP addresses, CIDR blocks, port ranges, bandwidth limits, or latency values. Invalid or malicious input could crash the tool, produce incorrect behavior, or be exploited for injection attacks. Fix: Implement comprehensive input validation for all network-related parameters. Validate IP addresses using net.ParseIP() and net.ParseCIDR(). Validate port ranges (0-65535). Validate bandwidth and latency values are within reasonable ranges. Reject invalid input with clear error messages.
• Medium · No Error Handling Evidence — throttler/ipfw.go, throttler/pfctl.go, throttler/tc.go. The visible file structure provides no evidence of comprehensive error handling or logging for system command execution failures. This could mask security issues, privilege escalation attempts, or system misconfiguration. Fix: Implement comprehensive error handling for all system command invocations. Log all executed commands and their results (without sensitive data). Validate exit codes and stderr output. Return meaningful error messages to users.
• Medium · Incomplete Platform Support Documentation — README.md, comcast.go. The README indicates Windows support 'may be possible' but is not implemented. The tool heavily depends on Unix-like system tools, which could lead to compatibility issues, platform-specific vulnerabilities, or users attempting to use it on unsupported systems without proper warnings. Fix: Add explicit platform detection and validation at startup. Return clear error messages on unsupported platforms. Document all platform-specific behaviors, requirements, and limitations. Consider implementing Windows support or officially deprecating it.

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.