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/sundowndev/phoneinfoga 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 4mo ago

• Last commit 4mo ago
• 6 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 4mo ago
• ⚠ Concentrated ownership — top contributor handles 74% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

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

What it runs against: a local clone of sundowndev/phoneinfoga — 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 sundowndev/phoneinfoga | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.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 ≤ 153 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.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 "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "cmd/root.go" \\
  && ok "cmd/root.go" \\
  || miss "missing critical file: cmd/root.go"
test -f "lib/remote/scanner.go" \\
  && ok "lib/remote/scanner.go" \\
  || miss "missing critical file: lib/remote/scanner.go"
test -f "lib/number/number.go" \\
  && ok "lib/number/number.go" \\
  || miss "missing critical file: lib/number/number.go"
test -f "lib/remote/remote.go" \\
  && ok "lib/remote/remote.go" \\
  || miss "missing critical file: lib/remote/remote.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 153 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~123d)"
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/sundowndev/phoneinfoga"
  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).

PhoneInfoga is a Go-based OSINT framework that gathers intelligence on international phone numbers by combining basic carrier/location data with external API queries, web scraping, and reputation checks. It exposes scanning capabilities via a REST API (Swagger-documented), CLI (Cobra), and Vue.js web UI, allowing users to identify phone owners, carriers, line types, and VoIP providers without claiming real-time tracking. Monolithic structure: cmd/ contains CLI entry points (root.go, scan.go, serve.go for REST API), lib or scanner packages likely hold the core scanning logic, web/ directory (inferred from Swagger docs reference) holds the REST API definitions, and a separate Vue frontend (24KB in repo) serves the web UI. The build/build.go suggests cross-platform binary generation via GoReleaser (.goreleaser.yml present).

Security researchers, OSINT practitioners, and penetration testers who need to enumerate phone number metadata during reconnaissance phases; also appealing to developers building phone intelligence features who want a pluggable scanner architecture.

Stable but officially unmaintained—the README states 'This project is stable but unmaintained. Upcoming bugs won't be fixed and repository could be archived at any time.' It has strong CI/CD (GitHub Actions: build.yml, codeql-analysis.yml, release.yml), test coverage tracking (Coveralls badge), and Docker support, indicating it was mature at freeze point, but no active development is expected.

Low immediate risk for static use cases, but high risk for long-term deployment: single maintainer (sundowndev), archived status means no security patches, ~25 transitive dependencies including pinned google.golang.org/api v0.92.0 (2022-era), and reliance on external scanner APIs that may break without notice. The 'unmaintained' status is the primary risk.

Project is in maintenance mode with no active development—no recent commits or PRs visible in the provided data. The last evidence of activity is CI/CD workflow files (build.yml, dockerimage-next.yml, homebrew.yml, release.yml) and Dependabot configuration (.github/dependabot.yml) indicating automated dependency updates were running at freeze.

Clone the repo, install Go 1.20+, run make build (Makefile present), or go build ./cmd/... to compile the CLI binary. For the web UI, make serve likely starts the Gin server on localhost:8080. Binaries land in bin/ directory (.gitkeep present).

Daily commands: For CLI: ./bin/phoneinfoga scan --number +1234567890. For REST API + web UI: phoneinfoga serve (starts Gin server, Vue frontend likely served at localhost:8080 or compiled into binary). Environment config via .env (godotenv dependency present).

• main.go — Application entry point that initializes the CLI and serves as the bootstrap for all phoneinfoga operations.
• cmd/root.go — Root Cobra command definition; every CLI invocation flows through this command hierarchy.
• lib/remote/scanner.go — Core Scanner interface that all information-gathering plugins must implement; defines the contract for extensibility.
• lib/number/number.go — Phone number parsing and validation logic using nyaruka/phonenumbers; foundation for all scanning operations.
• lib/remote/remote.go — Orchestrates execution of multiple scanners in parallel; central coordinator for all remote data gathering.
• cmd/serve.go — Gin-based REST API server setup; entry point for web service deployment alongside CLI.
• lib/output/console.go — Formats and displays scan results to console; handles presentation of unified scanner data.

Add a New Built-in Scanner

1. Create new scanner file in lib/remote/ implementing the Scanner interface from lib/remote/scanner.go (Name(), Description(), Run() methods) (lib/remote/newscanner.go)
2. Register scanner in lib/remote/init.go by adding it to the scanners slice in initScanners() (lib/remote/init.go)
3. Add corresponding test file with unit tests matching existing scanner test patterns (lib/remote/newscanner_test.go)
4. If scanner requires external API calls, add supplier interface in lib/remote/suppliers/ and mock in mocks/ for testing (lib/remote/suppliers/newsupplier.go)

Add a New REST API Endpoint

1. Define route handler function in cmd/serve.go that accepts *gin.Context and returns scanner results (cmd/serve.go)
2. Register route using gin router instance (e.g., router.GET or router.POST) in serve command setup (cmd/serve.go)
3. Parse request parameters, call lib/remote remote orchestrator, and return formatted JSON response (cmd/serve.go)

Add a New Output Format

1. Create new file in lib/output/ implementing the Output interface with Format() and Write() methods (lib/output/newformat.go)
2. Register formatter in cmd/scan.go or relevant command by adding to output format selection logic (cmd/scan.go)
3. Add test file with golden file comparisons matching lib/output/testdata/ pattern (lib/output/newformat_test.go)

Create External Scanner Plugin

1. Create Go project implementing Scanner interface from lib/remote/scanner.go in plugin module (examples/plugin/customscanner.go)
2. Build as shared library (.so on Linux/Mac, .dll on Windows) using Go plugin package (examples/plugin/README.md)
3. Place compiled plugin in plugins directory; lib/remote/local_scanner.go will auto-discover and load it (lib/remote/local_scanner.go)

• Go 1.20 — Single binary deployment, fast compilation, goroutines enable parallel scanner execution, strong stdlib for HTTP/CLI
• Cobra (CLI framework) — Professional command structure with subcommands, flags, and help; industry standard for Go CLIs
• Gin (HTTP framework) — Lightweight REST API server for web deployment; minimal overhead for serving scanner results
• nyaruka/phonenumbers — Robust international phone number parsing and validation; handles region codes and formatting automatically
• Go plugin system (local_scanner.go) — Runtime-loadable scanner plugins (.so files); enables third-party scanner contributions without recompilation
• Logrus (logging) — Structured logging with levels and hooks; consistent debugging across CLI and API server modes

• Synchronous parallel scanner execution with goroutines + channels

  • Why: Simplicity; no need for async/await or complex state management
  • Consequence: Slowest scanner determines total time; no per-scanner timeouts reduce robustness if a remote API hangs

• Plugin system via Go plugins (.so) rather than subprocess/gRPC

  • Why: Minimal overhead and direct memory access for plugin results
  • Consequence: Platform-specific compilation required; plugins crash brings down main process; development friction for plugin authors

• Single binary with embedded scanners vs. modular services

  • Why: Ease of distribution; users download one binary and get full functionality out of the box
  • Consequence: Tight coupling between CLI and scanners; harder to scale individual scanner services independently

• No built-in caching or rate limiting

  • Why: Scope: focus on CLI and API layer; rate limiting is user's responsibility via external proxies/middleware
  • Consequence: Repeated scans of same number hit APIs multiple times; risk of API bans without user-side protection

• Authentication/authorization (no user accounts, API key management, or multi-tenant support)
• Data persistence (no database; results are transient, printed or returned immediately)
• Real-time alerts or monitoring (one-off scans, not ongoing surveillance)
• SIM swapping, advanced carrier verification (scope limited to public lookups and search engines)
• Windows GUI application (CLI and REST API only)

External API keys likely required for full functionality (Google APIs in dependencies suggest custom API config). Scanner behavior depends on third-party services (phone books, social APIs) that may rate-limit or change. The project assumes Go 1.20+ (go.mod specifies this). Mock HTTP responses via gock.v1 in tests mean live scanner tests may fail if APIs change. No obvious environment variable docs in file list—check examples/ and docs/getting-started/ for .env template. Vue frontend build (24KB suggests pre-compiled) may require separate build step not visible in this data.

• OSINT (Open Source Intelligence) — Core mission of PhoneInfoga is OSINT—understanding how public data aggregation from APIs, phone books, and web search engines works is essential to using and extending the tool.
• Phone Number Formatting & Validation (E.164 Standard) — PhoneInfoga uses nyaruka/phonenumbers to parse and validate international formats; understanding E.164 and ITU recommendations is crucial for scanner accuracy.
• Plugin Architecture / Interface-Based Extensibility — The customscanner.go example shows PhoneInfoga is built on an interface-based plugin pattern; you'll need to understand Go interfaces to add new scanners.
• REST API Design & Swagger/OpenAPI Documentation — The serve.go command exposes a Swagger-documented REST API; understanding HTTP semantics and OpenAPI specs is needed to modify or extend API endpoints.
• Cross-Platform Binary Compilation with GoReleaser — .goreleaser.yml shows PhoneInfoga uses GoReleaser for multi-OS builds (Linux, macOS, Windows); understanding this workflow is essential if you need to build or distribute custom versions.
• HTTP Mocking & Contract Testing with gock — Tests use gopkg.in/h2non/gock.v1 to mock external API responses; understanding how to mock HTTP interactions is key for writing reliable unit tests for scanners.

• twilight-sparkle/oss-phonenumber-tools — Alternative Go phone OSINT tools that may have active forks or inspiration
• giswqs/geemap — Complementary OSINT geolocation framework that pairs with phone number intel
• sherlock-project/sherlock — Popular Python OSINT framework for username/social media hunting; similar reconnaissance philosophy
• woj-ciech/Sync.shark — Go-based OSINT sync tool that shares phone enumeration and data aggregation patterns

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 test coverage for lib/remote/googlecse_scanner.go

The googlecse_scanner.go file exists but has no corresponding _test.go file in the file structure. Given that other lib modules have test coverage (filter_test.go, number_test.go, console_test.go), this scanner should have unit tests. This is critical for an information gathering tool where scanner reliability is paramount. Tests should cover API error handling, response parsing, and edge cases.

• [ ] Create lib/remote/googlecse_scanner_test.go with test fixtures
• [ ] Add tests for Google CSE API initialization and error scenarios using the existing gock.v1 HTTP mocking dependency
• [ ] Add tests for parsing and validating phone number search results
• [ ] Ensure tests follow the pattern used in lib/output/console_test.go and lib/filter/filter_test.go

Implement integration tests for CLI commands in cmd/ package

The cmd/ package (root.go, scan.go, scanners.go, serve.go, version.go) lacks visible test files. As these are user-facing CLI entry points using Cobra, integration tests would verify the actual CLI behavior, error handling, and output formatting match documentation. This would catch regressions early.

• [ ] Create cmd/scan_test.go with tests for the scan command using actual scanner execution
• [ ] Create cmd/serve_test.go to test REST API server startup and endpoint health checks
• [ ] Create cmd/version_test.go to verify version output format matches docs/getting-started/usage.md
• [ ] Use table-driven tests to cover both success and error cases for each command

Add missing scanners documentation and examples in docs/getting-started/scanners.md

The file docs/getting-started/scanners.md exists but the lib/remote/ directory contains at least googlecse_scanner.go with no corresponding documentation section. Given the example plugin in examples/plugin/customscanner.go, contributors need clear documentation on available scanners, their APIs, rate limits, and how to create custom ones. This directly supports new contributor onboarding.

• [ ] Document each scanner in lib/remote/ (googlecse_scanner, and any others) with API keys required, rate limits, and data types returned
• [ ] Add a 'Creating Custom Scanners' section referencing examples/plugin/customscanner.go with step-by-step instructions
• [ ] Include a scanner architecture diagram or table showing scanner dependencies and their respective lib/remote files
• [ ] Add real-world examples showing scanner output format from docs/resources/formatting.md

• Add unit tests for cmd/scanners.go—file list shows cmd/ but no cmd/scanners_test.go, leaving scanner selection logic untested.
• Document the custom scanner plugin interface in docs/getting-started/—examples/plugin/ exists but no guide in docs/ explaining how to write one.
• Migrate deprecated go-openapi dependencies (go-openapi/spec, go-openapi/swag in go.sum) to current versions to reduce unmaintained transitive dependencies.

• High · Outdated Go Version in Docker Build — Dockerfile (line: FROM golang:1.20.6-alpine AS go_builder). The Dockerfile uses golang:1.20.6-alpine which is outdated. Go 1.20 reached end-of-life in December 2023. Using outdated Go versions exposes the application to known security vulnerabilities in the Go runtime and standard library. Fix: Update to the latest stable Go version (1.21 or 1.22+). Modify the base image to golang:1.22-alpine or later.
• High · Outdated Alpine Base Image — Dockerfile (line: FROM alpine:3.18). The final stage uses alpine:3.18 which is outdated. Alpine 3.18 is no longer receiving security updates. Using outdated base images introduces known CVEs into the container. Fix: Update to alpine:latest or alpine:3.19+ to ensure security patches are included.
• High · Outdated Node.js Version in Docker Build — Dockerfile (line: FROM node:20.9.0-alpine AS client_builder). The Dockerfile uses node:20.9.0-alpine which is outdated. Node.js 20.9.0 is no longer receiving security updates as newer patch versions exist. This may contain unpatched vulnerabilities. Fix: Update to node:20-alpine (latest 20.x LTS) or node:22-alpine. Use a more recent LTS version.
• High · Outdated Dependencies in go.mod — go.mod. Multiple dependencies are outdated and may contain known vulnerabilities: sirupsen/logrus v1.8.1 (released 2021), spf13/cobra v1.1.3 (released 2021), and google.golang.org/api v0.92.0 (outdated). These old versions lack security patches. Fix: Run 'go get -u ./...' to update all dependencies to their latest versions. Review go.mod and update to: sirupsen/logrus v1.9.x, spf13/cobra v1.7.x+, google.golang.org/api v0.152.0+.
• Medium · No Security Headers Configuration Visible — cmd/serve.go (Gin server implementation). The Gin web framework is used (lib/remote/remote.go, cmd/serve.go) but no evidence of security headers (HSTS, CSP, X-Frame-Options, etc.) configuration is visible in the codebase structure. Fix: Implement middleware to add security headers: Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security. Use gin middleware or OWASP guidelines.
• Medium · Exposed Port Without Rate Limiting Evidence — Dockerfile (line: EXPOSE 5000) and cmd/serve.go. The application exposes port 5000 (Dockerfile: EXPOSE 5000) for the Gin web server without visible rate limiting or DDoS protection mechanisms in the file structure. Fix: Implement rate limiting middleware in Gin. Use libraries like github.com/gin-contrib/ratelimit or implement custom middleware to prevent abuse.
• Medium · External API Calls Without Input Validation Evidence — lib/remote/ (scanner implementations). The codebase makes external API calls (googlecse_scanner, googlesearch_scanner, numverify_scanner, ovh_scanner) but input validation patterns are not evident in the file structure for phone number sanitization before API calls. Fix: Validate and sanitize phone numbers using the phonenumbers library before making external API requests. Implement strict input validation for all external API parameters.
• Medium · Potential Information Disclosure via Error Messages — lib/remote/ and cmd/scan.go. An information gathering framework that exposes phone number data risks leaking sensitive information through verbose error messages or API responses, particularly when querying external services. Fix: Implement proper error handling that doesn't expose sensitive details. Log detailed errors server-side only. Return generic error messages to clients.
• Low · Missing SBOM (Software Bill of — undefined. undefined Fix: undefined

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.