feat: TeamPCP PyPI campaign detection — IOC ledger, litellm .pth tests, import-time spec

Turn the telnyx/litellm (TeamPCP) supply-chain analysis into detection, across three tracks. No new check and no scope/gate change: tracks 1-2 reuse VC-003 and VC-002e; track 3 is spec + decision only.

1. IOC ledger (VC-003): docs/ioc-teampcp.example.json flags litellm 1.82.8 and telnyx 4.87.1/4.87.2; test loads the shipped feed and asserts it matches the compromised versions but not a clean 4.85.0.

2. litellm .pth (Track A): analyzer tests assert the real .pth trigger reads obfuscation+exec while a benign bootstrap import does not; check tests assert VC-002e fires on the former and stays silent on the latter.

3. telnyx import-time gap (Track B): payload in telnyx/_client.py runs on import, out of the install-surface model. Recorded as a boundary in D-165 and specified in docs/VC-002L-python-import-time.md (scoped, advisory-only, corpus-gated) — no code until the spec is met.

Validation: go test ./... green, vet clean, build ok. E2E: scan -ioc blocks telnyx@4.87.1 (exit 1, VC-003 block).

Author: MoSLoF

docs/DECISIONS.md

@@ -6887,3 +6887,36 @@ is the encoded contrast plus this entry, and extracting the construction for a r
 as the refactor it would be rather than smuggled into a bug fix. Declared stays empty until pom reading is
 its own decision. And the engine's raw fallback still writes `pkg:eco/name@version` for any FUTURE
 ecosystem that gains asserted resolution before its identity seam — the pattern to copy is this one.
+
+## D-165 — the Python import-time module surface is a known gap, held out of scope until a spec is met
+
+**Trigger:** the TeamPCP telnyx 4.87.1 / 4.87.2 compromise (analyzed 2026-03-27; recorded in
+[ioc-teampcp.example.json](ioc-teampcp.example.json)). The malicious code was injected into
+`telnyx/_client.py` — an ordinary SDK runtime module — as module-level code that runs on `import telnyx`.
+depSNORT's PyPI install-surface model (`AnalyzePython`) reads exactly three entrypoints: `setup.py`,
+`pyproject.toml` build-backend, and `.pth` files. All three are install- or interpreter-startup triggers;
+none is an ordinary module. The telnyx payload sidesteps every one of them and is invisible to the shipped
+analyzer. The sibling litellm 1.82.8 sample, by contrast, used a `.pth` file and IS in scope — its
+detection is pinned by the Track-A tests added alongside this entry.
+
+**The decision is a boundary, not a feature.** Extending static analysis to read ordinary runtime modules
+is a real scope expansion, and — per the zero-silent-failure and gate-vs-severity disciplines — expanding
+it quietly, or letting a broad new surface gate a build, would be worse than the gap. Import-time code is
+overwhelmingly benign (config loading, plugin registration, capability probing); a naive "scan every `.py`
+at import" is a false-positive catastrophe. So the decision is: **acknowledge the gap explicitly, keep it
+out of scope, and require a met specification before any code lands.** The specification is
+[VC-002L-python-import-time.md](VC-002L-python-import-time.md): a narrow, capability-gated
+`AnalyzePythonLoadTime` analyzer (mirroring npm's OPU-31 `AnalyzeLoadTime`, bounded by the same
+`maxLoadTimeRefs` cap), reusing the existing `scanCaps` and the D-25/D-160 stripping pipeline, feeding the
+existing VC-002 family with synthetic `module-load:` hooks. It ships **advisory-only** and earns a gate
+class only through the corpus evaluation in the spec's §7 — never before.
+
+**Coverage, not truth.** Until the analyzer exists, an import-time payload in a non-entrypoint Python
+module is unseen. That is a coverage limitation, and it is now named here and in the spec rather than
+implied by a clean scan. A scan that does not read a package's runtime modules must not be read as evidence
+that those modules are safe — the frontier is the module tree, and it is disclosed, not laundered.
+
+Residual limitations: this entry covers Python only. npm's entry-module import-time case is already handled
+by `AnalyzeLoadTime`; npm NON-entry runtime modules (a `lib/` file not reachable through `exports`) are the
+same class of gap and are noted here as a parallel, not closed. Other ecosystems' runtime-module surfaces
+are separate notes if and when a sample motivates them.

docs/VC-002L-python-import-time.md

@@ -0,0 +1,132 @@
+# VC-002L — Python import-time module surface (design note)
+
+Status: **proposal**. Not yet implemented. If adopted it lands as a new analyzer
+`AnalyzePythonLoadTime` in `internal/installsurface/`, wired through the pypi
+adapter, feeding the existing VC-002 family — and a decision record. The
+scope-boundary decision to keep this OUT of scope until the spec is met is
+already recorded as [D-165](DECISIONS.md).
+
+The trigger is a real sample: the **telnyx 4.87.1 / 4.87.2** compromise (TeamPCP
+campaign). See [`ioc-teampcp.example.json`](ioc-teampcp.example.json).
+
+---
+
+## 1. One line
+
+Malicious code injected into an **ordinary runtime module** (e.g. an SDK's own
+`telnyx/_client.py`) that executes on `import` is a real activation surface the
+tool does not currently assess. Assess it the way we already assess install
+hooks — walk import-reachable modules, run `scanCaps`, emit synthetic hooks — but
+**advisory-only** and behind a hard false-positive budget, because import-time
+code is overwhelmingly benign.
+
+## 2. The gap this closes
+
+depSNORT's PyPI install-surface model reads exactly three entrypoints
+(`AnalyzePython` in `internal/installsurface/analyze.go`): `setup.py`,
+`pyproject.toml` build-backend, and `.pth` files. All three are **install- or
+interpreter-startup** triggers. None of them is an ordinary module.
+
+The telnyx attack sidesteps every one of them: the payload lives in
+`telnyx/_client.py`, a normal SDK module, as module-level code that runs on
+**`import telnyx`** — a *runtime* event, not an install event. depSNORT never
+reads that file, so the compromise is invisible to static analysis today. This is
+confirmed by the subsystem map: PyPI has no import-time module analyzer at all,
+and npm's `AnalyzeLoadTime` (the OPU-31 RedC2 fix) only covers *declared entry
+modules*, not arbitrary runtime modules.
+
+This note does NOT propose reading every `.py` file in a package — that is a
+false-positive catastrophe (import-time code is where packages legitimately load
+config, register plugins, and run version checks). It proposes a **narrow,
+capability-gated** analyzer.
+
+## 3. Attack hypothesis
+
+> An attacker who can publish a package version injects credential-harvesting or
+> loader code into a module that the SDK's public API imports, so it runs on
+> first `import` in any consuming application — no lifecycle hook, no `.pth`, no
+> `setup.py` change that a hook scanner would see.
+
+## 4. Detection design
+
+New analyzer `AnalyzePythonLoadTime(entryModules, read)` mirroring npm's
+`AnalyzeLoadTime`:
+
+1. **Entry set, bounded.** Start from the package's declared public surface —
+   the top-level package `__init__.py` and the modules it imports — not the whole
+   tree. Follow intra-package imports to a bounded depth (reuse the
+   `maxLoadTimeRefs = 16` cap), disclosing the bound via `Surface.Truncated` →
+   `GapTruncated` exactly as the npm analyzer does. Never follow into
+   dependencies.
+2. **Module-level only.** Scan code that runs at import: top-level statements and
+   the bodies of module-level calls — not function/method bodies that only a
+   later call would reach.
+3. **Reuse the capability model unchanged.** Run the existing `scanCaps`. Emit a
+   synthetic `module-load:<relpath>` hook when the scanned code carries an
+   **escalating** capability, never on bare presence of code.
+
+The analyzer only produces facts; the existing VC-002 family judges. No new
+check logic is required — a `module-load:` hook with `obfuscation+exec` fires
+VC-002e, with `network+credentials` fires VC-002d, etc.
+
+## 5. Evidence / confidence / gate
+
+| Field | Value |
+|---|---|
+| Required evidence | module-level code reachable from the package's import surface with an escalating capability (`network`, `credentials`, `exec`, `obfuscation`, `cradle`) |
+| Optional reinforcing | co-located with a version delta that ADDED the capability (VC-010), first-seen publisher (VC-011) |
+| Excluded conditions | capability basis is a display-sink string, a docstring/comment, or a URL literal (reuse the D-25/D-160 stripping pipeline before scanning) |
+| Severity ceiling | **advisory** on first ship, regardless of capability — see D-165 |
+| Gate eligibility | **none initially.** Promotion to gate-eligible requires the corpus evaluation in §7 |
+| Coverage prerequisite | the module tree was actually read; a truncated/unread walk is disclosed as a gap, never as "clean" |
+
+Rationale for the advisory ceiling: import-time execution is a vastly broader and
+more benign surface than install hooks. Blocking on it before a measured
+false-positive rate would violate the gate-vs-severity discipline (§22 of the
+contract). It ships in shadow, earns its gate class with evidence, or never gets
+one.
+
+## 6. Known false positives (the make-or-break set)
+
+Legitimate packages routinely run capability-adjacent code at import:
+
+- lazy config load that reads environment variables (`env`, never alone an
+  escalation — `credentials` requires a NAMED secret);
+- plugin registries that `importlib.import_module` by name (`exec`-adjacent);
+- packages that shell out at import for capability detection (`subprocess` +
+  version parse);
+- vendored code that base64-decodes embedded data (fonts, certs) without
+  executing it (`obfuscation` requires decode PAIRED with an exec sink).
+
+The benign corpus MUST include these, harvested from real scans the way
+`legitimate.go` was built. The FP rate on this set is the gating metric.
+
+## 7. Promotion gate (corpus evaluation)
+
+Before this analyzer feeds anything above advisory:
+
+1. malicious corpus: the telnyx `_client.py` shape + synthetic variants
+   (split strings, renamed funcs, indirection) — all detected;
+2. benign corpus (§6): measured false-positive rate at or below the documented
+   budget;
+3. adversarial: added to `internal/ecosystem/conformance/`;
+4. shadow run over a representative real project set, FP rate reported.
+
+## 8. Test vectors
+
+- **Positive:** module-level `os.environ['AWS_SECRET_ACCESS_KEY']` +
+  `urllib.request.urlopen(...)` in a non-entry module → `module-load:` hook with
+  `credentials+network` → VC-002d.
+- **Positive:** the telnyx shape — base64 decode + `subprocess.Popen` at module
+  level → `obfuscation+exec` → VC-002e.
+- **Negative (FP control):** module-level `os.environ.get('MYAPP_DEBUG')` + a
+  plugin-registry loop → no escalating capability → no hook.
+- **Negative (FP control):** `base64.b64decode(EMBEDDED_FONT)` with no exec sink
+  → no `obfuscation` → no hook.
+
+## 9. What is explicitly NOT in scope
+
+- Reading dependency modules (only the scanned package's own tree).
+- Non-Python ecosystems (npm's entry-module case is already handled; other
+  ecosystems are separate notes).
+- Any gate-class outcome before §7 is satisfied.

docs/ioc-teampcp.example.json

@@ -0,0 +1,34 @@
+{
+  "version": 1,
+  "source": "reference feed — TeamPCP PyPI credential-theft campaign (compiled from public payload analysis, 2026-03)",
+  "generated": "2026-08-30T00:00:00Z",
+  "indicators": [
+    {
+      "ecosystem": "pypi",
+      "name": "litellm",
+      "version": "1.82.8",
+      "severity": "critical",
+      "category": "malware",
+      "reference": "TEAMPCP-2026-0324",
+      "note": "litellm_init.pth credential stealer; .pth auto-exec on any interpreter start; exfil hxxps://models[.]litellm[.]cloud, C2 hxxps://checkmarx[.]zone/raw; systemd persistence sysmon.service; K8s node worm"
+    },
+    {
+      "ecosystem": "pypi",
+      "name": "telnyx",
+      "version": "4.87.1",
+      "severity": "critical",
+      "category": "malware",
+      "reference": "TEAMPCP-2026-0327",
+      "note": "malicious telnyx/_client.py runs on import; Linux path active; WAV-steg payload from 83[.]142[.]209[.]203:8080; same RSA key + tpcp.tar.gz exfil as litellm. Windows path dormant in this build (Setup() case bug)"
+    },
+    {
+      "ecosystem": "pypi",
+      "name": "telnyx",
+      "version": "4.87.2",
+      "severity": "critical",
+      "category": "malware",
+      "reference": "TEAMPCP-2026-0327",
+      "note": "as 4.87.1 but the one-character fix (setup()) arms the Windows path: WAV-steg -> PE (AdaptixC2) in Startup as msbuild.exe; implant C2 checkmarx[.]zone:8443"
+    }
+  ]
+}

internal/check/builtin/teampcp_pth_test.go

@@ -0,0 +1,56 @@
+package builtin
+
+// Track-A validation for the TeamPCP litellm 1.82.8 .pth vector: the analyzer
+// half is asserted in internal/ecosystem/pypi/installsurface_test.go
+// (TestAnalyzePythonLitellmInitPth / ...BenignBootstrapPth); these two pin the
+// CHECK outcome on the resulting hook, so the whole path — .pth line to verdict —
+// is covered on both the malicious and the benign side.
+
+import (
+	"testing"
+
+	"ihbv.io/depsnort/internal/check"
+	"ihbv.io/depsnort/internal/finding"
+	"ihbv.io/depsnort/internal/graph"
+)
+
+// pthHookGraph builds a pypi package with one pth:import install hook carrying
+// the given capabilities.
+func pthHookGraph(pkgID string, caps ...string) *graph.Graph {
+	g := graph.New()
+	g.AddNode(&graph.Node{ID: pkgID, Kind: graph.KindPackage, Ecosystem: "pypi", Name: "p", Version: "1.0.0"})
+	hookID := "hook:" + pkgID + "#pth:import"
+	hn := g.AddNode(&graph.Node{ID: hookID, Kind: graph.KindInstallHook, Ecosystem: "pypi", Name: "pth:import"})
+	if hn.Attr == nil {
+		hn.Attr = map[string]string{}
+	}
+	for _, c := range caps {
+		hn.Attr["cap."+c] = "true"
+	}
+	g.AddEdge(pkgID, hookID, graph.EdgeDeclaresHook)
+	return g
+}
+
+// TestVC002eFiresOnLitellmPth: the litellm .pth shape (base64 decode + exec)
+// resolves to obfuscation+exec, which must produce exactly one VC-002e
+// decode-and-execute finding at gate-eligible severity.
+func TestVC002eFiresOnLitellmPth(t *testing.T) {
+	g := pthHookGraph("pkg:pypi/litellm@1.82.8", "obfuscation", "exec")
+	fs := (HookObfuscated{}).Run(&check.Context{Graph: g})
+	if len(fs) != 1 {
+		t.Fatalf("litellm .pth (obfuscation+exec) must fire one VC-002e finding; got %+v", fs)
+	}
+	if fs[0].GateClass != finding.GateEligible {
+		t.Errorf("VC-002e gate class = %v, want gate-eligible (decode-and-execute is not, alone, block-class)", fs[0].GateClass)
+	}
+}
+
+// TestVC002eQuietOnBenignPth: a benign bootstrap-import .pth carries exec only
+// (the analyzer's deliberate lower bound on any import line) and must NOT fire
+// VC-002e. This is the false-positive boundary the litellm case sits beyond.
+func TestVC002eQuietOnBenignPth(t *testing.T) {
+	g := pthHookGraph("pkg:pypi/goodpkg@1.0.0", "exec")
+	if fs := (HookObfuscated{}).Run(&check.Context{Graph: g}); len(fs) != 0 {
+		t.Errorf("exec-only pth must not fire VC-002e; got %+v", fs)
+	}
+}

internal/datasource/ioc/ioc_test.go

@@ -60,3 +60,41 @@ func TestLoadRejectsUnknownVersion(t *testing.T) {
 		t.Error("an unsupported feed version must be rejected")
 	}
 }
+
+// TestTeamPCPExampleLedger keeps the shipped reference feed
+// (docs/ioc-teampcp.example.json) honest: it must parse, and it must match the
+// compromised releases by exact version while leaving a clean release alone. If
+// the feed schema drifts, this fails rather than silently loading nothing.
+func TestTeamPCPExampleLedger(t *testing.T) {
+	f, err := Load(filepath.Join("..", "..", "..", "docs", "ioc-teampcp.example.json"))
+	if err != nil {
+		t.Fatalf("shipped TeamPCP ledger must load: %v", err)
+	}
+	if f.Len() != 3 {
+		t.Fatalf("ledger Len=%d, want 3 (litellm 1.82.8, telnyx 4.87.1, telnyx 4.87.2)", f.Len())
+	}
+
+	// Every compromised release must match by exact version.
+	compromised := []struct{ purl, eco, name, ver string }{
+		{"pkg:pypi/litellm@1.82.8", "pypi", "litellm", "1.82.8"},
+		{"pkg:pypi/telnyx@4.87.1", "pypi", "telnyx", "4.87.1"},
+		{"pkg:pypi/telnyx@4.87.2", "pypi", "telnyx", "4.87.2"},
+	}
+	for _, c := range compromised {
+		ind := f.Match(c.purl, c.eco, c.name, c.ver)
+		if ind == nil {
+			t.Errorf("%s must match the TeamPCP ledger", c.purl)
+			continue
+		}
+		if ind.Severity != "critical" {
+			t.Errorf("%s severity = %q, want critical", c.purl, ind.Severity)
+		}
+	}
+
+	// A clean telnyx release must NOT match — a version-pinned indicator is
+	// exact, so the ledger must never over-block a good version of a package
+	// that also shipped a bad one.
+	if ind := f.Match("pkg:pypi/telnyx@4.85.0", "pypi", "telnyx", "4.85.0"); ind != nil {
+		t.Errorf("a clean telnyx release must not match the ledger; got %+v", ind)
+	}
+}

internal/ecosystem/pypi/installsurface_test.go

@@ -147,6 +147,62 @@ func TestAnalyzePythonSafePthFile(t *testing.T) {
 	}
 }
 
+// pthHookHasCap reports whether the single pth:import hook carries a capability.
+func pthHookHasCap(h installsurface.Hook, c installsurface.Capability) bool {
+	for _, cap := range h.Caps {
+		if cap == c {
+			return true
+		}
+	}
+	return false
+}
+
+// TestAnalyzePythonLitellmInitPth reproduces the real litellm 1.82.8 trigger
+// (TeamPCP campaign, TEAMPCP-2026-0324): a single .pth line that spawns a
+// detached interpreter which base64-decodes and exec()s an embedded payload. The
+// credential theft itself lives in the decoded blob — a coverage frontier the
+// static analyzer cannot read — but the decode-and-execute shape is visible on
+// the .pth line and is what drives VC-002e. The analyzer must surface obfuscation
+// AND exec so the check can fire.
+func TestAnalyzePythonLitellmInitPth(t *testing.T) {
+	pth := map[string]string{
+		"litellm_init.pth": `import os, subprocess, sys; subprocess.Popen([sys.executable, "-c", "import base64; exec(base64.b64decode('aW1wb3J0IHNvY2tldA=='))"])`,
+	}
+	s := installsurface.AnalyzePython("", "", pth)
+	if len(s.Hooks) != 1 {
+		t.Fatalf("expected 1 pth hook, got %d", len(s.Hooks))
+	}
+	h := s.Hooks[0]
+	if h.Name != "pth:import" {
+		t.Errorf("hook name = %q, want pth:import", h.Name)
+	}
+	if !pthHookHasCap(h, installsurface.CapObfuscation) {
+		t.Error("missing obfuscation capability (base64.b64decode) — VC-002e would not fire")
+	}
+	if !pthHookHasCap(h, installsurface.CapExec) {
+		t.Error("missing exec capability (subprocess/exec)")
+	}
+}
+
+// TestAnalyzePythonBenignBootstrapPth is the false-positive control: a real,
+// legitimate pattern — a .pth that imports a package's own bootstrap module.
+// analyzePthFile flags any import line as exec (a deliberate lower bound), so a
+// hook IS produced, but it must NOT gain the obfuscation capability, so VC-002e
+// (decode-and-execute) stays silent on it. This is the line the litellm case
+// must sit on the far side of.
+func TestAnalyzePythonBenignBootstrapPth(t *testing.T) {
+	pth := map[string]string{
+		"pkg_bootstrap.pth": "import mypkg._bootstrap",
+	}
+	s := installsurface.AnalyzePython("", "", pth)
+	if len(s.Hooks) != 1 {
+		t.Fatalf("expected 1 pth hook for the import line, got %d", len(s.Hooks))
+	}
+	if pthHookHasCap(s.Hooks[0], installsurface.CapObfuscation) {
+		t.Error("a plain bootstrap import must not read as obfuscation — this would be a false positive")
+	}
+}
+
 // TestExtractInstallSurfaceNilFetcher pins the CORRECTED contract (D-141).
 //
 // This test previously asserted the opposite — that a nil fetcher returns no