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/OpenEthan/SMSBoom 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.

AVOID — Looks unmaintained — solo project with stale commits

• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)

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

What it runs against: a local clone of OpenEthan/SMSBoom — 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 OpenEthan/SMSBoom | 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 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 808 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "OpenEthan/SMSBoom(\\.git)?\\b" \\
  && ok "origin remote is OpenEthan/SMSBoom" \\
  || miss "origin remote is not OpenEthan/SMSBoom (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"

# 4. Critical files exist
test -f "smsboom.py" \\
  && ok "smsboom.py" \\
  || miss "missing critical file: smsboom.py"
test -f "smsboom_GUI.py" \\
  && ok "smsboom_GUI.py" \\
  || miss "missing critical file: smsboom_GUI.py"
test -f "api.json" \\
  && ok "api.json" \\
  || miss "missing critical file: api.json"
test -f "utils/req.py" \\
  && ok "utils/req.py" \\
  || miss "missing critical file: utils/req.py"
test -f "utils/models.py" \\
  && ok "utils/models.py" \\
  || miss "missing critical file: utils/models.py"

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

SMSBoom is a bulk SMS bombing tool that automates sending large volumes of SMS messages to phone numbers by aggregating multiple third-party SMS APIs defined in api.json configuration files. It's now deprecated due to legal/judicial suspension, but the codebase demonstrates multi-threaded SMS API orchestration with support for custom API endpoints, keyword substitution ([timestamp], [phone]), and proxy rotation (HTTP/SOCKS4/SOCKS5). Modular architecture with separate CLI (smsboom.py) and GUI (smsboom_GUI.py) entry points, a utils/ package containing request logic (utils/req.py), database operations (utils/sql.py), logging (utils/log.py), and data models (utils/models.py). API endpoints are externalized in api.json and GETAPI.json, with debug/ folder containing deprecated API scrapers (spider-api.py, tou_api.py) and test data.

Security researchers, penetration testers, and abuse engineers who need to understand SMS API exploitation patterns and rate-limiting vulnerabilities—though the project is now suspended and should not be used for actual attacks. Contributors would be those studying async HTTP request patterns, API aggregation architectures, or threat modeling for telecom systems.

Abandoned and suspended. The repository shows a 2024 judicial suspension notice from HK Judiciary, indicating legal action halted development. The codebase has a pyinstaller-packaged Windows EXE release pipeline (.github/workflows/run.yaml) and appears to have been active through early 2024, but the README explicitly states the repo is suspended and no longer maintained.

Extremely high legal and ethical risk—the project is explicitly suspended due to judicial action. From a code perspective: minimal test coverage (no test directory visible), single maintainer (OpenEthan), 52KB of unvetted Python code aggregating SMS APIs, dependency on pinned versions (requirements.txt), and likely outdated API endpoints (debug/spider-api.py suggests scraping). Using or forking this for its intended purpose exposes users to criminal liability.

Nothing—the project was suspended in March 2024 by HK Judiciary. The README explicitly states 'the repository has been suspended!' with judicial references. No active development, PRs, or issues are being processed. The codebase is in a frozen deprecated state with a note that the project violated local laws.

Historical reference only (project is suspended). For educational inspection only: git clone https://github.com/OpenEthan/SMSBoom.git && pip install -r requirements.txt && python smsboom.py --help. The codebase required Python 3.8+, used pipenv for virtual environments (pipenv install), and shipped pre-built Windows EXE binaries (smsboom_pyinstall.exe).

Daily commands: For Windows (binary, deprecated): smsboom_pyinstall.exe run -t 64 -p <phone_number>. For development (Python, deprecated): pipenv shell && python smsboom.py --help. Example: python smsboom.py run -t 64 -p 19800000000 -f 60 -i 30 -e (64 threads, 60 waves, 30s interval, proxies enabled).

• smsboom.py — Primary CLI entry point orchestrating SMS bombing campaigns; must understand core request/threading logic before extending
• smsboom_GUI.py — GUI wrapper using Flask; understand how it marshals user input to the core bombing engine
• api.json — Configuration file defining SMS provider endpoints, headers, and payload templates; all bombing targets are declared here
• utils/req.py — HTTP request abstraction layer handling proxies, user-agents, retries; critical for bypassing provider rate-limits
• utils/models.py — Pydantic data models validating API schema and request parameters; schema changes here ripple through entire codebase
• requirements.txt — Dependencies including httpx, loguru, pydantic; no pinned versions—audit for security/compatibility issues

• smsboom.py (Python threading, argparse) — CLI orchestrator; parses arguments, loads config, spawns worker threads, aggregates results
  • Failure mode: If config load fails or threads crash, entire campaign halts with no partial success tracking
• utils/req.py (httpx, proxy libs) — HTTP request abstraction; sends crafted POST/GET to SMS providers with proxy, auth headers, retries
  • Failure mode: Network errors or provider blocks cause request to fail silently unless logged; no circuit breaker
• api.json (JSON) — Provider endpoint registry; declares URL, method, headers, body template with [phone]/[timestamp] substitution
  • Failure mode: Malformed JSON or missing fields cause Pydantic validation error at startup
• smsboom_GUI.py (Flask, HTML/JS) — Flask web UI; accepts user input (phone, count), dispatches to core engine, returns HTML response
  • Failure mode: GUI server crash does not stop CLI; no session management or input sanitization

• User → smsboom.py — CLI args (phone, count, interval) or HTTP POST from GUI
• smsboom.py → api.json — Load provider endpoints and payload templates
• smsboom.py → utils/req.py — Dispatch HTTP requests with (phone, provider config, proxy)
• utils/req.py → SMS Provider — Send crafted HTTP POST/GET with [phone] and [timestamp] substituted
• SMS Provider → utils/req.py — HTTP response (200, 429, error codes)
• utils/req.py → utils/log.py — Log request outcome (success, retry, failure)

Add a new SMS provider endpoint

1. Define provider schema in api.json with url, method, headers, and body template using [phone] and [timestamp] placeholders (api.json)
2. Validate endpoint by running smsboom.py with --url flag or testing via GUI (smsboom.py)
3. If provider has custom auth, extend req.py with new proxy or header injection logic (utils/req.py)

Add rate-limit or proxy handling

1. Update req.py to add proxy rotation strategy (e.g., select random proxy from pool on each request) (utils/req.py)
2. Adjust timeout and retry logic in the same file; test with --interval flag in CLI (smsboom.py)

Add a new GUI tab or input field

1. Extend Flask route handlers and HTML templates in smsboom_GUI.py to accept new parameters (smsboom_GUI.py)
2. Pass new parameters to core bombing function (likely in smsboom.py main loop) (smsboom.py)

• httpx — Async-capable HTTP client with built-in proxy and header management; avoids requests library limitations
• pydantic — Type-safe validation of api.json schema; ensures consistency across all provider endpoints
• loguru — Structured logging with colored output and file rotation; aids debugging and forensic analysis
• Flask (GUI) — Lightweight web framework for quick prototyping; no production-grade overhead needed
• Threading/Async — Parallelize SMS requests to maximize throughput; reduce per-request latency impact

• Configuration via static JSON (api.json) rather than database

  • Why: Simplifies deployment and versioning; no schema migrations required
  • Consequence: Providers must be manually edited and redeployed; no hot-reload capability

• Multi-threading instead of pure async

  • Why: Easier integration with blocking I/O and CLI argument parsing
  • Consequence: GIL contention under high concurrency; async would be more scalable

• No authentication or rate-limiting on GUI

  • Why: Minimalist design for rapid testing
  • Consequence: Vulnerable to abuse if exposed on network; unsuitable for production

• Provide legitimate SMS delivery service
• Production-grade API infrastructure
• Cross-platform GUI (Windows focus)
• Real-time analytics dashboard
• Legal compliance mechanisms
• Multi-user access control

• Hardcoded proxy and User-Agent pools (Medium) — utils/req.py: User-Agent and proxy list are likely static; no dynamic refresh or feedback mechanism when providers block them
• No error recovery strategy (High) — smsboom.py: If a thread crashes or a provider rejects all requests, campaign continues without retry logic or circuit breaker
• Placeholder replacement via string interpolation (Low) — api.json, utils/req.py: Simple regex replace for [phone] and [timestamp]; vulnerable to injection if provider JSON contains malformed templates
• No rate-limit awareness (High) — utils/req.py: Does not parse HTTP 429 or Retry-After headers; blindly retries without exponential backoff
• Unvalidated external input in GUI (Medium) — smsboom_GUI.py: Flask routes do not sanitize phone number or count inputs; no XSS/CSRF protection

• utils/req.py (I/O blocking) — Serial retry loop blocks thread waiting for timeout; could use async/await for concurrent retries
• sm (undefined) — undefined

Critical warning: This is a suspended/illegal project. For educational analysis: (1) API endpoints in api.json are third-party services that likely changed or block since 2024 suspension, (2) debug/ folder contains deprecated scraper scripts (spider-api.py, tou_api.py) that rely on fragile HTML parsing and are probably broken, (3) Windows EXE build requires C-extension compatibility with Windows 10 x64 specifically (pyinstaller constraint mentioned in README), (4) Proxy lists are not bundled—users need external proxy sources, (5) No SSL certificate pinning or verification bypass in utils/req.py makes the tool vulnerable to MITM if used over untrusted networks.

• API Aggregation & Templating — SMSBoom's core design treats third-party SMS APIs as interchangeable plugins via JSON config with [phone] and [timestamp] placeholder substitution—understanding this pattern helps identify how a single tool can target dozens of services without code changes
• Proxy Chaining (HTTP + SOCKS) — The -e flag enables proxy rotation across HTTP/SOCKS4/SOCKS5 protocols to obfuscate source IP; critical for understanding how attack tools evade rate-limiting and geo-blocking
• Thread Pool Orchestration — The -t (threads) parameter spawns a pool of concurrent request workers; understanding thread safety and request queuing is essential for high-concurrency attack patterns
• User-Agent Randomization & Obfuscation — SMSBoom rotates User-Agent headers to bypass bot detection; this is a fundamental evasion technique visible in utils/log.py that security engineers need to understand for both defense and threat modeling
• Rate-Limit Amplification via API Bundling — By aggregating 20+ SMS APIs in a single tool, attackers can distribute load across providers to exceed individual rate limits; this is a multiplexing attack pattern not obvious from single-service analysis
• Payload Injection & Keyword Substitution — The [timestamp] and [phone] placeholders allow dynamic payload generation per request; this is similar to template injection vulnerabilities and demonstrates how attackers customize payloads at scale
• Stateless Distributed Bombing via SQLite Logging — utils/sql.py logs each request to a local database, enabling an attacker to track success/failure rates and retry patterns across millions of SMS without maintaining in-memory state

• strues/bully — Similar SMS bombing tool for Android; demonstrates the same architectural pattern of aggregating multiple free SMS APIs for malicious purposes
• aio-libs/httpx — The HTTP client library used by SMSBoom's utils/req.py for async/sync requests; understanding httpx internals is critical for modifying request patterns
• encode/httpcore — Low-level HTTP transport dependency of httpx; relevant for proxy implementation and custom connection pooling in utils/req.py
• pallets/click — CLI framework used by smsboom.py for argument parsing; understanding Click decorators is needed to modify command-line interface
• samuelcolvin/pydantic — Data validation library used in utils/models.py for API request/response schema enforcement; critical for extending API integrations

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 utils/ modules (log.py, models.py, req.py, sql.py)

The repo has no test directory despite containing core utility modules. The utils/ folder has critical functionality (logging, request handling, SQL operations, data models) that lack test coverage. This is especially important given the project's complexity with async HTTP requests (httpx), database operations (sql.py), and data validation (pydantic models). Adding tests would prevent regressions and validate the refactoring mentioned in the TODO.

• [ ] Create tests/test_utils/ directory structure
• [ ] Add unit tests for utils/req.py (httpx request wrapper with proxy support)
• [ ] Add unit tests for utils/sql.py (database operations)
• [ ] Add unit tests for utils/models.py (pydantic data models)
• [ ] Add unit tests for utils/log.py (loguru logging configuration)
• [ ] Update requirements-dev.txt with pytest and pytest-asyncio
• [ ] Add GitHub Actions workflow (.github/workflows/test.yaml) to run pytest on push

Add GitHub Actions workflow to validate api.json and debug/touapi.json schemas

The repo heavily relies on custom api.json configuration files (mentioned in features: 'define interfaces via custom api.json') but has no validation pipeline. With api.json, debug/touapi.json, debug/touapi.json, and touapi.json in the codebase, a schema validation workflow would catch malformed configurations before runtime and support the mentioned feature of custom interface definitions.

• [ ] Create a JSON schema file (schemas/api.schema.json) defining valid api.json structure
• [ ] Create a GitHub Actions workflow (.github/workflows/validate-config.yaml)
• [ ] Add jsonschema validation step using Python or ajv
• [ ] Validate all api.json files in repo against schema on push
• [ ] Add validation script (scripts/validate_configs.py) that can be run locally
• [ ] Update README with JSON schema documentation

Extract and document the API interface definition format with examples

The repo's core feature is 'define interfaces via custom api.json with keyword replacement [timestamp], [phone]' but the api.json format is not documented anywhere. GETAPI.json and api.json exist but lack schema documentation. This blocks contributors from understanding how to extend the SMS provider integrations. Creating clear documentation with examples would enable community contributions to add new SMS providers.

• [ ] Analyze existing api.json and GETAPI.json files to reverse-engineer the schema
• [ ] Create docs/API_CONFIGURATION.md documenting the JSON schema with examples
• [ ] Document keyword replacement system: [timestamp], [phone], and any other tokens
• [ ] Add example configurations showing different HTTP methods (POST, GET) with headers
• [ ] Document proxy configuration options (http, socks4, socks5) mentioned in features
• [ ] Add examples for common SMS providers to docs/ directory

• Audit and document the API schema in api.json: Create a formal OpenAPI/JSON Schema spec for the SMS endpoint config format (url, method, headers, payload templates) since it's currently free-form and undocumented—this helps security researchers understand the attack surface without reverse-engineering GETAPI.json
• Add unit tests for utils/models.py and utils/req.py: The codebase has zero visible test files; add pytest fixtures for mocking httpx responses and validating request templating (e.g., does [phone] correctly substitute in payloads, does [timestamp] format correctly?) to prevent regression
• Document the proxy rotation logic in utils/req.py with inline examples: The code supports HTTP/SOCKS4/SOCKS5 but there's no guide on proxy list format or failover behavior; add docstrings with concrete examples of proxy URLs and error handling behavior

• Critical · Malicious Application Purpose — smsboom.py, smsboom_GUI.py, entire codebase. SMSBoom is explicitly designed for SMS bombing/flooding attacks. The repository has been suspended by Hong Kong judiciary due to its malicious nature. The application enables unauthorized mass SMS transmission to phone numbers, which constitutes harassment, denial of service, and potential legal violations. Fix: Do not use, deploy, or contribute to this application. It violates computer fraud and abuse laws in most jurisdictions. Users should be aware of severe legal consequences.
• High · Outdated and Vulnerable Dependencies — requirements.txt, requirements-dev.txt. Multiple dependencies have known vulnerabilities: httpx==0.22.0 (vulnerable versions exist), pydantic==1.9.0 (outdated, security patches released), certifi==2021.10.8 (outdated). These packages contain publicly disclosed CVEs. Fix: Update all dependencies to latest secure versions. Use: httpx>=0.23.3, pydantic>=2.0, certifi>=2023.7.22. Run pip-audit or safety check to identify CVEs.
• High · Hardcoded Configuration Files — api.json, GETAPI.json, debug/api_tou.json, debug/hz-web.json, debug/touapi.json. Multiple API configuration files (api.json, GETAPI.json, debug/*.json) likely contain hardcoded API endpoints, credentials, or phone numbers without encryption or environment variable protection. Fix: Move sensitive configuration to environment variables or encrypted config files. Never commit credentials to version control. Use .gitignore to exclude sensitive files and implement secret management.
• High · SQL Injection Risk — utils/sql.py, utils/models.py. The utils/sql.py file suggests direct database interactions. Without proper parameterized queries, the application may be vulnerable to SQL injection attacks, especially when processing phone numbers or API responses. Fix: Use parameterized queries/prepared statements for all database operations. Implement ORM frameworks like SQLAlchemy with proper input validation and type enforcement.
• High · Insecure HTTP Requests — utils/req.py. utils/req.py likely performs HTTP requests to untrusted SMS APIs. Without proper SSL/TLS validation, certificate pinning, or response validation, the application is vulnerable to MITM attacks and injection of malicious payloads. Fix: Enforce certificate verification (verify=True), implement timeout values, validate response content-type, sanitize and validate all responses, use HTTPS only.
• Medium · Inadequate Input Validation — smsboom.py, utils/req.py, utils/models.py. Phone number and API endpoint parameters are processed without apparent sanitization. This could lead to injection attacks when constructing URLs, headers, or database queries. Fix: Implement comprehensive input validation for phone numbers (regex/format validation), API endpoints (URL parsing/validation), and all user inputs. Use Pydantic for schema validation.
• Medium · Docker Security Issues — Dockerfile. Dockerfile builds from python:3.9-alpine without explicit security hardening. No non-root user is specified, no health checks defined, and pip dependencies are installed without hash verification. Fix: Create non-root user, use specific base image digest, add pip install --no-cache-dir, implement multi-stage builds, add health checks, use pip install --require-hashes for dependency verification.
• Medium · Logging Sensitive Information — utils/log.py, throughout codebase. loguru (utils/log.py) is used for logging without apparent filtering of sensitive data. Phone numbers, API keys, and request bodies could be logged in plaintext. Fix: Implement log filtering to redact phone numbers, API keys, and sensitive data. Use structured logging, never log authentication tokens or PII. Implement proper log rotation and retention policies.
• Medium · No Rate Limiting or Abuse Controls — sm. The application is designed to send mass SMS requests without internal rate limiting, throttling, or abuse detection mechanisms, facilitating denial-of-service attacks. 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.