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/kasketis/netfox 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 2y ago

• 23+ active contributors
• Distributed ownership (top contributor 27% of recent commits)
• MIT licensed
• CI configured
• ⚠ Stale — last commit 2y ago
• ⚠ 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 kasketis/netfox repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kasketis/netfox.

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

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

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

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

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

# 4. Critical files exist
test -f "netfox/Core/NFX.swift" \\
  && ok "netfox/Core/NFX.swift" \\
  || miss "missing critical file: netfox/Core/NFX.swift"
test -f "netfox/Core/NFXProtocol.swift" \\
  && ok "netfox/Core/NFXProtocol.swift" \\
  || miss "missing critical file: netfox/Core/NFXProtocol.swift"
test -f "netfox/Core/NFXHTTPModel.swift" \\
  && ok "netfox/Core/NFXHTTPModel.swift" \\
  || miss "missing critical file: netfox/Core/NFXHTTPModel.swift"
test -f "netfox/Core/NFXHTTPModelManager.swift" \\
  && ok "netfox/Core/NFXHTTPModelManager.swift" \\
  || miss "missing critical file: netfox/Core/NFXHTTPModelManager.swift"
test -f "netfox/Core/NFXWindowController.swift" \\
  && ok "netfox/Core/NFXWindowController.swift" \\
  || miss "missing critical file: netfox/Core/NFXWindowController.swift"

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

Netfox is a lightweight iOS/macOS network debugging library that intercepts and displays all HTTP(S) requests made by your app in a built-in UI—including requests from third-party libraries, UIWebViews, and your own code. It provides one-line setup via NFX.start() and surfaces request/response details, timing, and statistics through an in-app inspector triggered by device shake. Monolithic framework: /netfox/Core/ contains 17 Swift files with central logic (NFX.swift is the main entry point, NFXProtocol.swift handles URLSession interception, NFXHTTPModel.swift models captured requests, NFXHTTPModelManager.swift manages the store). Platform-specific UI in /netfox/iOS/ and /netfox/OSX/ (controllers, cells, xibs). NFXWindowController.swift overlays the debug UI. Supporting modules include NFXAssets.swift for resources and NFXAuthenticationChallengeSender.swift for HTTP auth handling.

iOS and macOS developers debugging network issues, API integration problems, or third-party library behavior. QA engineers testing API contracts. Anyone building apps that need to audit or troubleshoot live network traffic without external proxy tools.

Actively maintained and production-ready. Currently at v1.21.0 with Swift 5+ support and CI via Travis. Swift 4 (v1.19.0) and Swift 3.2 (v1.12.1) legacy releases available. Multi-platform support (iOS/macOS) with CocoaPods, Carthage, and SPM distribution indicate mature package management. Single maintainer (kasketis) with regular but infrequent commits suggest stable, not rapidly evolving codebase.

Single-maintainer repository with no visible open PR backlog or recent commits beyond version maintenance. Tight URLProtocol hook into iOS networking stack means OS updates or security-related URLSession changes could break functionality. No visible test suite in file listing suggests limited regression coverage. Low dependency count (mostly platform frameworks) reduces external risk, but lack of active community contribution could slow adoption of new iOS features (e.g., async/await patterns).

No visible active development in provided data; repo appears in steady-state maintenance mode. Last updates appear to be version bumps and SPM beta support integration. No open issues or PRs listed in file structure.

git clone https://github.com/kasketis/netfox.git
cd netfox
# Via CocoaPods (if integrating into an app):
echo 'pod "netfox"' >> Podfile && pod install
# Or open netfox.xcodeproj directly in Xcode to inspect the framework source
open netfox.xcodeproj

Daily commands: Netfox is a library, not an app. To test: open netfox.xcodeproj, select netfox_ios or netfox_osx scheme, and build (Cmd+B). To use in your own app: import netfox then call NFX.start() in AppDelegate.application(_:didFinishLaunchingWithOptions:). Trigger the UI by shaking the device or programmatically with NFX.show().

• netfox/Core/NFX.swift — Main singleton entry point for netfox initialization and lifecycle management—every integration starts here.
• netfox/Core/NFXProtocol.swift — URLProtocol subclass that intercepts all HTTP/HTTPS requests—the core mechanism enabling network capture.
• netfox/Core/NFXHTTPModel.swift — Data model representing captured HTTP request/response pairs—foundation for all logging and inspection.
• netfox/Core/NFXHTTPModelManager.swift — Manages in-memory storage and retrieval of captured HTTP models—critical for state management.
• netfox/Core/NFXWindowController.swift — Manages the floating debug window UI presentation and lifecycle—entry point for visual debugging interface.
• netfox/Core/NFXListController.swift — Abstract base controller for displaying list of captured requests—platform-agnostic UI foundation.
• netfox/Core/NFXDetailsController.swift — Abstract base for displaying request/response details—enables inspection of captured network traffic.

Add a new settings option

1. Define the setting constant in NFXConstants.swift (netfox/Core/NFXConstants.swift)
2. Add UI control in iOS settings controller (netfox/iOS/NFXSettingsController_iOS.swift)
3. Add UI control in macOS settings controller (netfox/OSX/NFXSettingsController_OSX.swift)
4. Read the setting in the appropriate handler (e.g., NFXProtocol.swift or NFXWindowController.swift) (netfox/Core/NFXProtocol.swift)

Add a new request/response detail viewer

1. Create new controller subclassing NFXGenericBodyDetailsController (netfox/Core/NFXGenericBodyDetailsController.swift)
2. Register the new controller in NFXDetailsController to detect content-type (netfox/Core/NFXDetailsController.swift)
3. Implement platform-specific views in both iOS and OSX folders if needed (netfox/iOS/NFXDetailsController_iOS.swift)

Add a new statistics metric

1. Add calculation logic in NFXHTTPModelManager for aggregating data (netfox/Core/NFXHTTPModelManager.swift)
2. Update iOS statistics view to display metric (netfox/iOS/NFXStatisticsController_iOS.swift)
3. Update macOS statistics view to display metric (netfox/OSX/NFXStatisticsController_OSX.swift)
4. Format output if needed using NFXHelper (netfox/Core/NFXHelper.swift)

Capture additional request metadata

1. Add property to NFXHTTPModel data structure (netfox/Core/NFXHTTPModel.swift)
2. Populate the property in NFXProtocol during request/response capture (netfox/Core/NFXProtocol.swift)
3. Display the metadata in NFXDetailsController (netfox/Core/NFXDetailsController.swift)

• URLProtocol subclass (NFXProtocol.swift) — Only standard Apple API that can transparently intercept all URLSession requests without app code changes—enables 'one-line setup'
• Platform-specific UI layers (iOS/ and OSX/ folders) — UIKit and AppKit have fundamentally different API surfaces; separate implementations avoid abstraction overhead while supporting both iOS and macOS
• Singleton pattern (NFX.swift) — Global interception and UI state must be accessible from anywhere without dependency injection; matches standard iOS debugging tool patterns (Xcode, Reveal)
• In-memory storage (NFXHTTPModelManager) — Fast query and filtering of captured requests; SQLite would add complexity for a development-time tool without proportional benefit

• Separate iOS and macOS UI code instead of shared abstraction

  • Why: Each platform has idiomatic conventions and UI constraints; a shared abstraction would create verbose wrappers
  • Consequence: Code duplication (~2x UI code) but native performance and UX per platform

• Store all models in memory rather than disk/database

  • Why: Minimizes setup overhead and latency; targets debug/development use, not production analytics
  • Consequence: Memory grows with number of requests; app restart clears logs (acceptable for debug tool)

• Use floating window overlay on app rather than separate debug app

  • Why: Single-line integration; no need for IPC or complex setup
  • Consequence: Shares memory with app being debugged; cannot debug app crashes that terminate the process

• Capture all requests (no filtering by URL) at protocol level

  • Why: Ensures 3rd-party library requests are visible; user can filter in UI
  • Consequence: May generate many models for chatty apps; requires UI to handle large datasets efficiently

• Real-time streaming to external services or remote debugging
• Network request modification/mocking (view-only inspection)
• Persistent storage or log export beyond manual screenshots

URLProtocol registration must happen on the main thread and before any network requests; calling NFX.start() too late may miss early requests. The shake gesture only works on physical devices or certain simulator configurations. NSURLSession instances created before NFX.start() won't be intercepted (protocol must be registered globally via URLProtocol.register()). Encryption/certificate pinning libraries may interfere with request interception. No explicit handling for HTTP/2 Server Push or WebSocket traffic visible in file list.

• URLProtocol — Netfox's entire interception mechanism relies on registering a custom URLProtocol subclass to globally hook URLSession requests; understanding URLProtocol lifecycle and delegate callbacks is essential to modifying the core interception logic
• URLSession Delegation & HTTPURLResponse — The framework captures request/response metadata via URLSession delegate methods; knowledge of URLSessionDelegate, URLSessionDataDelegate, and HTTPURLResponse properties is needed to add new request/response fields
• Device Motion & Shake Gesture Detection — Netfox triggers the debug UI via device shake using UIEventSubtype.motionShake; understanding motion event handling is key to alternative trigger mechanisms or gesture customization
• HTTP Authentication Challenge (CFNetworking) — NFXAuthenticationChallengeSender.swift handles HTTP Basic/Digest auth and client certificate challenges; required for debugging APIs with authentication without breaking the request flow
• Custom UIViewController Container & View Hierarchy Injection — NFXWindowController overlays the debug UI on top of the app window without disrupting the view controller hierarchy; understanding UIWindow management, view controller containment, and responder chain is needed for UI improvements
• In-Memory & Persistent Storage Patterns — NFXHTTPModelManager stores captured requests in memory (and possibly to disk); understanding data persistence strategies informs changes to request history limits, filtering, or export
• Cross-Platform UI Abstraction (UIKit vs AppKit) — Separate iOS and macOS code paths (netfox/iOS/ vs netfox/OSX/) require conditional compilation and platform-specific view/controller patterns; critical for maintaining feature parity across platforms

• Alamofire/Alamofire — Popular HTTP networking library for iOS; netfox integrates with and debugs requests from Alamofire-based apps
• AFNetworking/AFNetworking — Legacy Objective-C networking framework; netfox explicitly supports capturing AFNetworking requests via URLProtocol hooking
• swiiftly/Bagel — Alternative macOS network debugger app; serves same inspection role but as standalone desktop tool instead of in-app framework
• Moya/Moya — Network abstraction layer built on Alamofire; netfox can debug Moya requests by intercepting the underlying URLSession calls

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 GitHub Actions CI workflow to replace Travis CI

The repo currently uses .travis.yml for CI/CD, which is outdated. GitHub Actions is now the modern standard and integrates seamlessly with GitHub. This would ensure the project has active, maintained CI with better visibility and faster feedback. The current .travis.yml file is minimal and should be migrated to .github/workflows/ci.yml.

• [ ] Create .github/workflows/ci.yml with jobs for iOS and macOS builds
• [ ] Add test steps for both netfox_ios and netfox_osx schemes defined in .github/ISSUE_TEMPLATE
• [ ] Include pod install and swift build validation
• [ ] Test against multiple Swift/Xcode versions
• [ ] Remove or deprecate .travis.yml after migration is verified

Add comprehensive unit tests for NFXHTTPModel and NFXHTTPModelManager

The core data models (netfox/Core/NFXHTTPModel.swift and NFXHTTPModelManager.swift) lack test coverage. These are critical for request/response tracking and filtering. Adding unit tests would ensure data integrity, improve maintainability, and provide examples for contributors.

• [ ] Create Tests/ directory with NFXHTTPModelTests.swift
• [ ] Add tests for NFXHTTPModel initialization, property mutations, and data serialization
• [ ] Add tests for NFXHTTPModelManager CRUD operations (add, retrieve, filter, delete requests)
• [ ] Test edge cases like nil headers, empty bodies, and large payloads
• [ ] Integrate tests into the Xcode project scheme

Document platform-specific code organization and add tests for iOS/macOS platform detection

The codebase has significant platform-specific implementations split across netfox/iOS and netfox/OSX directories, but there's no documentation explaining the platform abstraction strategy. Additionally, the conditional compilation logic in NFXHelper.swift and NFXHelper_iOS.swift should have tests to prevent platform-specific bugs.

• [ ] Create ARCHITECTURE.md documenting the iOS vs macOS conditional compilation pattern
• [ ] Add unit tests for NFXHelper.swift platform detection and helper methods
• [ ] Add tests for platform-specific UI controller initialization (NFXDetailsController_iOS vs NFXDetailsController_OSX)
• [ ] Document which files are iOS-only, macOS-only, and cross-platform in ARCHITECTURE.md
• [ ] Add compile-time assertions or tests to catch missing platform implementations

• Add unit tests for NFXHTTPModel.swift and NFXHTTPModelManager.swift to improve test coverage (none visible in file structure); could start with XCTest basics for model parsing and filtering logic
• Implement async/await support in NFXProtocol.swift to modernize the URLProtocol delegate methods for Swift 5.5+ codebases; current implementation likely uses completion handlers
• Create comprehensive documentation for NFXAuthenticationChallengeSender.swift behavior with HTTP Basic Auth and certificate challenges; add code examples to README showing how to handle auth dialogs in the debug UI

Netfox is a debugging library with a reasonable security posture for its intended use case (development/debug builds only). The primary concerns are ensuring it cannot be enabled in production and properly handling sensitive data during network interception. The library itself does not appear to have obvious code injection risks, hardcoded secrets, or critical dependency issues based on the visible file structure. However, the lack of visible strict build-time guards and the inherent risk of exposing sensitive network data warrants medium-severity findings. Recommendations focus on preventing production deployment and implementing data protection mechanisms.

• Medium · Network Traffic Interception Risk — netfox/Core/NFXProtocol.swift, netfox/Core/NFXHTTPModel.swift. As a network debugging library that intercepts HTTP/HTTPS traffic, netfox could potentially expose sensitive data (authentication tokens, API keys, PII) if the debugging interface is accessible in production builds or if captured data is not properly secured in memory. Fix: Implement strict build-time guards to ensure netfox is only active in development/debug builds. Add warnings in documentation about production usage. Consider implementing data redaction for sensitive headers (Authorization, API-Key, etc.). Ensure captured data is properly cleared from memory and never persisted to disk without encryption.
• Medium · Potential Information Disclosure via Debugging UI — netfox/Core/NFXDetailsController.swift, netfox/iOS/NFXDetailsController_iOS.swift, netfox/OSX/NFXDetailsController_OSX.swift. The library provides a debugging UI that displays all network request/response details including headers, bodies, and parameters. If the app is accidentally shipped with netfox enabled, this could expose sensitive information like tokens, keys, and user data. Fix: Add prominent warnings in documentation about ensuring netfox is disabled in production builds. Implement compile-time flags (e.g., #if DEBUG) to prevent accidental inclusion. Consider adding a runtime toggle that can be verified before shipping.
• Low · Missing Dependency Version Pinning — Package.swift, netfox.podspec. The Package.swift and netfox.podspec files are not provided in the analysis. Without explicit version constraints for dependencies, transitive vulnerabilities in updated dependencies could be introduced. Fix: Review and ensure all dependencies have explicit version constraints. Regularly audit dependencies for known vulnerabilities using tools like CocoaPods or SPM security scanners.
• Low · No Obvious Input Validation on Network Data — netfox/Core/NFXHTTPModel.swift, netfox/Core/NFXGenericBodyDetailsController.swift. While netfox primarily displays data, improper handling of malformed or exceptionally large network responses could potentially cause issues. No obvious validation of response sizes or formats is visible in file names. Fix: Implement size limits and validation for captured network data. Add safeguards against parsing extremely large responses or malformed data that could cause memory issues or crashes.

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.