The problem

Traditional scanners — Semgrep, Bandit, CodeQL — hunt CVEs and OWASP classes. Silent telemetry isn't a vulnerability in that sense, so it walks straight through every existing gate.

No Phone Home asks the question a privacy auditor actually asks:

Does this code take data about my machine and my identity, ship it over the network, and never check whether I said no?

It answers by running source-to-sink taint analysis over tree-sitter ASTs, then verifying whether each network egress is genuinely gated by a consent check such as DO_NOT_TRACK.

🔍 What it catches

1. Unguarded exfiltration

import socket, requests

host = socket.gethostname()                              # 1. tainted source
payload = {"device": host}                               # 2. taint propagates
requests.post("https://telemetry.dev/api", json=payload) # 3. egress, no guard  ❌

2. Inverted guards — the case most tools get backwards

if os.getenv("DO_NOT_TRACK"):
    requests.post(url, json=payload)   # ⛔ transmits *because* you opted out

A naive "is there an enclosing if mentioning DO_NOT_TRACK?" check calls this safe. No Phone Home reasons about polarity — which way the consent token points, and whether it is truthy or falsy where the sink actually runs — so it reports this at HIGH severity as a distinct INVERTED_GUARD verdict.

The same logic works across languages. In Go:

host, _ := os.Hostname()
if os.Getenv("DO_NOT_TRACK") != "" {
    http.Post(url, "application/json", host)  // ⛔ sends only when DNT *is* set
}

3. Guard clauses — how real code is actually written

def report():
    if os.getenv("DO_NOT_TRACK"):
        return                                   # ✅ dominating guard, correctly cleared
    requests.post(url, json={"host": socket.gethostname()})

An ancestor-only if walk misses this entirely, because a guard clause is not an enclosing conditional.

4. Telemetry hidden one call deep

def _send(payload):
    requests.post(URL, json=payload)             # sink lives here

def track():
    _send({"user": getpass.getuser()})           # ❌ still caught, via function summaries

This is how telemetry SDKs are actually structured, and it is invisible to a purely intraprocedural pass.

📦 Installation

Requires Python 3.10+. No other runtime — the tree-sitter grammars ship as prebuilt wheels.

From GitHub (works today):

pip install git+https://github.com/mkamranr/no-phone-home.git

From source (for development):

git clone https://github.com/mkamranr/no-phone-home.git
cd no-phone-home
pip install -e ".[dev]"
pytest          # 67 tests

Using uv:

uv venv && uv pip install -e ".[dev]"
uv run no-phone-home ./src

Note · A PyPI release (pip install no-phone-home) is planned — see the release workflow. Until then, install from GitHub as above.

🚀 Quick start

no-phone-home ./src                      # scan a directory
no-phone-home app.py                     # scan one file
no-phone-home . --format markdown        # Privacy Nutrition Label
no-phone-home . --list-rules             # see active rules

Typical output:

┏━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Sev     ┃ Rule   ┃ Location          ┃ Private data → destination   ┃ Guard      ┃
┡━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ HIGH    │ ST-001 │ metrics.py:34     │ socket.gethostname() →       │ UNGUARDED  │
│         │        │                   │ https://telemetry.dev/api    │            │
│ HIGH    │ ST-002 │ analytics.py:12   │ getpass.getuser() →          │ INVERTED   │
│         │        │                   │ https://api.mixpanel.com     │            │
└─────────┴────────┴───────────────────┴──────────────────────────────┴────────────┘
23 files scanned · 8 taint paths · 5 privacy violations
⛔ 1 inverted guard(s): data is sent on the branch where the user opted OUT.

📋 Output formats

The Privacy Nutrition Label gives non-engineers a readable summary:

## 📋 Privacy Nutrition Label
| Data Category | Detected Source | Egress Destination | Guard Status |
| :--- | :--- | :--- | :--- |
| **System Info** | `platform.node()` | `https://telemetry.dev/api` | ❌ **UNGUARDED** |
| **User Identity** | `os.userInfo()` | `https://api.mixpanel.com` | ✅ Guarded (`DO_NOT_TRACK`) |
| **Environment** | `process.env` | Local Log File | ℹ️ Internal Only |

⚙️ Continuous integration

GitHub Actions

No Phone Home ships as a composite action. SARIF uploads land in your repo's Security tab:

name: Privacy scan
on: [push, pull_request]

permissions:
  contents: read
  security-events: write

jobs:
  no-phone-home:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: mkamranr/no-phone-home@v0.1.0
        with:
          path: ./src
          fail-on: HIGH
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: no-phone-home.sarif

Or call the CLI directly:

- run: pip install git+https://github.com/mkamranr/no-phone-home.git
- run: no-phone-home ./src --format sarif --output results.sarif --fail-on HIGH

Exit codes

Distinguishing 1 from 2 is what makes it safe to gate a build on.

pre-commit

repos:
  - repo: https://github.com/mkamranr/no-phone-home
    rev: v0.1.0
    hooks:
      - id: no-phone-home

🎛️ CLI reference

no-phone-home [PATH] [OPTIONS]

Full details in docs/usage.md.

📐 Custom rules

Rules are declarative YAML — extending coverage needs no Python. Drop a .nph-rules.yml in your repo root:

version: "1.0"

rules:
  - id: ST-001
    name: Unchecked Hostname Exfiltration
    severity: HIGH
    language: python
    category: SYSTEM_INFO
    sources:
      - pattern: "socket.gethostname()"
      - pattern: "platform.node()"
    sinks:
      - pattern: "requests.post($URL, data=$DATA)"
    guards:
      - pattern: "os.getenv('DO_NOT_TRACK')"
    remediation: "Wrap the request in an explicit opt-out check."

Patterns are parsed with the same tree-sitter grammar as your code, so they're real syntax rather than regexes. $NAME is a metavariable wildcard.

📖 Full rule-authoring guide →

🔇 Suppression

Inline, scoped to a specific rule:

requests.post(url, json=payload)  # no-phone-home: ignore[ST-001]

Or snapshot an existing codebase and fail only on new findings:

no-phone-home . --write-baseline .nph-baseline.json   # once
no-phone-home . --baseline .nph-baseline.json         # in CI

🌐 Language support

All three languages run the same engine — taint propagation, same-file function summaries, and polarity-aware guard verification. Only rule coverage differs.

Adding a language means implementing one adapter protocol — the analyzer never names a tree-sitter node type directly. See docs/architecture.md.

🧠 How it works

[ Source Code ]
      │
      ▼
[ Parser (tree-sitter) ] ──► Language ASTs (Python, JS/TS, Go)
      │
      ▼
[ Normalized IR ]
      │
      ▼
[ Taint Engine ]
      ├── Source matching      (system / user / hardware APIs)
      ├── Propagation          (assignment, dicts, f-strings, concat)
      ├── Function summaries   (same-file, cross-function)
      └── Sink matching        (HTTP clients / telemetry SDKs)
      │
      ▼
[ Guard Evaluator ]  ──► GUARDED / UNGUARDED / INVERTED_GUARD / LOCAL_ONLY
      │
      ▼
[ Reporters ] ──► Table · Nutrition Label · JSON · SARIF

📖 Architecture deep dive →

⚠️ Honest limitations

This is a heuristic static analyzer, not a proof of absence.

It reads code without running it, so it will miss dynamically-constructed exfiltration (getattr, eval, reflection, runtime-assembled URLs), and it will sometimes flag benign code. A clean scan is not a certificate of privacy.

Its value is making silent telemetry visible and reviewable — not certifying innocence. Every finding carries a confidence level precisely so you can tell "definitely" from "worth a look".

Scope boundaries:

• First-party code only by default. Vendor directories are skipped; --include-deps opts in, at the cost of slower scans and findings you can't directly fix.
• Intraprocedural + same-file summaries. Taint crossing module boundaries is not tracked; a whole-program call graph is where scanners lose accuracy and speed.
• Hashing a value lowers confidence but does not clear taint — a hashed hardware ID is still a stable identifier.

📚 Documentation

🤝 Contributing

The highest-value contribution is rules and fixtures — both are YAML and plain sample code, no engine knowledge needed.

Every detection change ships with fixtures in both directions: a true_positive/ case and the correctly-guarded true_negative/ form. The corpus harness enforces 100% precision and recall, which is deliberate — for a privacy scanner a false positive costs more than a miss, because it's what gets the tool deleted from CI.

See CONTRIBUTING.md.

📄 License

Apache-2.0