muaddib-scanner 2.11.46 → 2.11.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muaddib-scanner",
-  "version": "2.11.46",
+  "version": "2.11.47",
   "description": "Supply-chain threat detection & response for npm & PyPI/Python",
   "main": "src/index.js",
   "bin": {

package/{self-scan-v2.11.46.json → self-scan-v2.11.47.json}

@@ -1,6 +1,6 @@
 {
   "target": "node_modules",
-  "timestamp": "2026-05-25T15:19:42.839Z",
+  "timestamp": "2026-05-25T18:50:42.771Z",
   "threats": [
     {
       "type": "string_mutation_obfuscation",

package/src/pipeline/processor.js

@@ -11,6 +11,10 @@ const { debugLog } = require('../utils.js');
 const { getPackageMetadata } = require('../scanner/npm-registry.js');
 const { checkReleaseZero } = require('../scanner/release-zero.js');
 const { checkUnclaimedMaintainerEmail, checkCompromisedDomain } = require('../scanner/email-domain.js');
+const { getPyPIPackageMetadata } = require('../scanner/pypi-registry.js');
+const { runPyPIMaintainerChecks } = require('../scanner/pypi-maintainer.js');
+const { checkPyPIReleaseZero } = require('../scanner/pypi-release-zero.js');
+const { detectScannedPackageName } = require('../scanner/python.js');
 
 // Auto-sandbox compound trigger : optional out-of-tree dependency. Lazy-load
 // it so the pipeline still works when the file is absent (some dev machines
@@ -247,6 +251,56 @@ async function process(threats, targetPath, options, pythonDeps, warnings, scann
     }
   }
 
+  // ───── PyPI side — same shape as the npm block above (v2.11.47, Phase 2) ─────
+  // Fetch PyPI registry metadata for the scanned package iff we can identify it
+  // (pyproject.toml / setup.py / setup.cfg). Same MUADDIB_NO_REGISTRY_FETCH
+  // master switch. Failure mode: silent (returns null), all downstream PyPI
+  // checks degrade gracefully.
+  if (
+    _pkgMeta &&
+    globalThis.process.env.MUADDIB_NO_REGISTRY_FETCH !== '1'
+  ) {
+    let pypiPackageName = null;
+    try {
+      pypiPackageName = detectScannedPackageName(targetPath);
+    } catch (err) {
+      debugLog('[PYPI-NAME] detect failed: ' + err.message);
+    }
+    if (pypiPackageName) {
+      try {
+        const pypiMeta = await getPyPIPackageMetadata(pypiPackageName);
+        if (pypiMeta) {
+          _pkgMeta.pypiPackageName = pypiPackageName;
+          _pkgMeta.pypiRegistryMeta = pypiMeta;
+        }
+      } catch (err) {
+        debugLog('[PYPI-REGISTRY-META] fetch failed for ' + pypiPackageName + ': ' + err.message);
+      }
+    }
+  }
+
+  if (_pkgMeta && _pkgMeta.pypiRegistryMeta) {
+    // PYPI-003 — release-zero (v0.x.x + age <30d). MEDIUM, composite-only.
+    try {
+      const rz = checkPyPIReleaseZero(_pkgMeta.pypiRegistryMeta.latest_version, _pkgMeta.pypiRegistryMeta);
+      if (rz) deduped.push(rz);
+    } catch (err) {
+      debugLog('[PYPI-RELEASE-ZERO] check failed: ' + err.message);
+    }
+    // MAINTAINER-005 + MAINTAINER-006, PyPI-flavoured (file → pyproject.toml,
+    // wording mentions PyPI). Same env opt-outs as npm
+    // (MUADDIB_EMAIL_DOMAIN_CHECK=0, MUADDIB_RDAP_CHECK=0).
+    try {
+      const pypiThreats = await runPyPIMaintainerChecks(
+        _pkgMeta.pypiPackageName,
+        _pkgMeta.pypiRegistryMeta
+      );
+      for (const t of pypiThreats) deduped.push(t);
+    } catch (err) {
+      debugLog('[PYPI-MAINTAINER] check failed: ' + err.message);
+    }
+  }
+
   // Cross-scanner compound: detached_process + suspicious_dataflow in same file
   // Catches cases where credential flow is detected by dataflow scanner, not AST scanner
   {

package/src/response/playbooks.js

@@ -498,6 +498,13 @@ const PLAYBOOKS = {
     'qui ne tracent que les "import X" statiques. Inspecter les appels suivants au module dynamiquement ' +
     'importe — combine a exec/subprocess/fetch indique malveillance avec haute confiance.',
 
+  pypi_release_zero:
+    'MEDIUM: Package PyPI v0.x.x publie il y a moins de 30 jours. Pattern de lure / ship-as-vulnerable. ' +
+    'Composite-only: cette regle seule ne suffit pas, mais combinee avec PYAST-001 (cmdclass) ou un IOC ' +
+    'string TrapDoor, c\'est un signal fort. Inspecter manuellement: qui est l\'auteur, est-ce que d\'autres ' +
+    'packages aux noms similaires ont ete publies le meme jour, est-ce que le code source ressemble a une ' +
+    'lib utile ou a un stub vide.',
+
   fork_exec_inline_interpreter:
     'HIGH: subprocess.X([<interpreter>, -e|-c, ...]) — fork-exec d\'un interpreteur inline ' +
     '(node -e, python -c, bash -c, ruby -e, perl -e, php -r, ...). Pattern transversal: Python ouvre ' +

package/src/rules/index.js

@@ -224,6 +224,19 @@ const RULES = {
     ],
     mitre: 'T1195.002'
   },
+  pypi_release_zero: {
+    id: 'MUADDIB-PYPI-003',
+    name: 'PyPI Release-Zero (v0.x.x recently published)',
+    severity: 'MEDIUM',
+    confidence: 'medium',
+    domain: 'malware',
+    description: 'Package PyPI dont la latest_version est 0.x.x (release-zero PEP 440) ET dont la premiere publication est < 30 jours. Pattern de lure / ship-as-vulnerable / typosquat-staging. Equivalent PyPI de PKG-022 cote npm. Composite-only : la severite reste MEDIUM pour eviter les FPs sur les vrais projets early-stage.',
+    references: [
+      'https://attack.mitre.org/techniques/T1195/002/',
+      'https://peps.python.org/pep-0440/'
+    ],
+    mitre: 'T1195.002'
+  },
 
   // PYSRC-001 a 008 — Python source scanner (TrapDoor PyPI gap, v2.11.25).
   // python.js est manifest-only ; ast.js/dataflow.js sont JS-only ; ioc-strings.js

package/src/scanner/pypi-maintainer.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * PyPI maintainer / metadata checks — wires the existing ecosystem-agnostic
+ * email-domain.js (MAINTAINER-005 MX + MAINTAINER-006 RDAP) onto PyPI
+ * metadata returned by pypi-registry.js.
+ *
+ * Created v2.11.47. Mirror of how npm calls these from processor.js, but
+ * for the PyPI side. We reuse the same threat types (`unclaimed_maintainer_email`,
+ * `compromised_email_domain`) — they're conceptually identical, only the
+ * registry context differs. We post-process the returned threats to swap the
+ * `file` field (package.json → pyproject.toml) and tweak the message wording
+ * so the operator sees "PyPI" not "npm" in the report.
+ */
+
+const {
+  checkUnclaimedMaintainerEmail,
+  checkCompromisedDomain
+} = require('./email-domain.js');
+
+/**
+ * Adapt an npm-flavoured threat from email-domain.js to a PyPI-flavoured one.
+ * Returns a new object (does not mutate the input).
+ */
+function adaptThreatToPyPI(threat, declarationFile) {
+  if (!threat || typeof threat !== 'object') return threat;
+  const adapted = { ...threat, file: declarationFile || 'pyproject.toml' };
+  if (typeof threat.message === 'string') {
+    adapted.message = threat.message
+      .replace(/\bnpm\b/g, 'PyPI')
+      .replace(/take over the account/g, 'take over the PyPI account');
+  }
+  return adapted;
+}
+
+/**
+ * Entry point for PyPI maintainer-domain checks.
+ *
+ * @param {string} packageName - PyPI package name being scanned.
+ * @param {object} pypiRegistryMeta - Output of getPyPIPackageMetadata().
+ *   Must have shape { maintainer_emails: string[], created_at: ISO | null }.
+ * @param {object} options - { resolveMx, fetchRdap, declarationFile } — first
+ *   two are forwarded to email-domain.js (test injection); declarationFile is
+ *   the path to display in threat.file (defaults to 'pyproject.toml').
+ * @returns {Promise<Array>} threats array (empty if metadata is missing or
+ *   the env opt-outs MUADDIB_EMAIL_DOMAIN_CHECK=0 / MUADDIB_RDAP_CHECK=0 are set).
+ */
+async function runPyPIMaintainerChecks(packageName, pypiRegistryMeta, options = {}) {
+  if (!pypiRegistryMeta || typeof pypiRegistryMeta !== 'object') return [];
+  if (!Array.isArray(pypiRegistryMeta.maintainer_emails) || pypiRegistryMeta.maintainer_emails.length === 0) {
+    return [];
+  }
+
+  const declarationFile = options.declarationFile || 'pyproject.toml';
+  // email-domain.js reads `meta.maintainer_emails` and `meta.created_at`.
+  // The shape matches one-to-one with what pypi-registry.js returns.
+  const helperMeta = {
+    maintainer_emails: pypiRegistryMeta.maintainer_emails,
+    created_at: pypiRegistryMeta.created_at
+  };
+
+  const threats = [];
+
+  let mxThreats = [];
+  try {
+    mxThreats = await checkUnclaimedMaintainerEmail(helperMeta, {
+      resolveMx: options.resolveMx
+    });
+  } catch { /* silent — same posture as email-domain.js */ }
+  for (const t of mxThreats) threats.push(adaptThreatToPyPI(t, declarationFile));
+
+  let rdapThreats = [];
+  try {
+    rdapThreats = await checkCompromisedDomain(helperMeta, {
+      fetchRdap: options.fetchRdap
+    });
+  } catch { /* silent */ }
+  for (const t of rdapThreats) threats.push(adaptThreatToPyPI(t, declarationFile));
+
+  return threats;
+}
+
+module.exports = {
+  runPyPIMaintainerChecks,
+  // Exposed for unit tests
+  _internal: { adaptThreatToPyPI }
+};

package/src/scanner/pypi-registry.js

@@ -0,0 +1,239 @@
+'use strict';
+
+/**
+ * PyPI registry metadata fetcher — mirror of `src/scanner/npm-registry.js`
+ * for the PyPI ecosystem. Closes the npm/PyPI asymmetry on the metadata axis.
+ *
+ * Created v2.11.47 to enable PyPI-side maintainer/email/release-zero
+ * detections (port of MAINTAINER-005/006/PKG-022 to PyPI).
+ *
+ * Architecture parity with npm-registry.js :
+ *  - built-in fetch (no external dep)
+ *  - 10s timeout, 3 retries with exponential backoff
+ *  - 429 backoff respecting Retry-After
+ *  - throttle via http-limiter.js semaphore (shared with npm — same MUAD'DIB
+ *    self-DoS protection ; rate budget is global, ok since target hosts differ)
+ *  - 5min in-process cache keyed by package name
+ *  - returns null on any failure (never throws — pipeline safety)
+ *  - gated upstream by `MUADDIB_NO_REGISTRY_FETCH === '1'` (same master switch)
+ *
+ * URL : https://pypi.org/pypi/<package>/json (canonical PEP 691 JSON API)
+ */
+
+const { debugLog } = require('../utils.js');
+const { acquireRegistrySlot, releaseRegistrySlot } = require('../shared/http-limiter.js');
+
+const PYPI_REGISTRY_URL = 'https://pypi.org/pypi';
+const REQUEST_TIMEOUT = 10000; // 10 seconds
+const MAX_RETRIES = 3;
+const CACHE_TTL = 5 * 60 * 1000; // 5 minutes — mirror npm-registry
+
+// PEP 503 normalized package name: lowercase letters / digits / `-` `_` `.`
+// Case-insensitive on input, server normalizes.
+const PYPI_PACKAGE_REGEX = /^[A-Za-z0-9_.-]{1,214}$/;
+
+// In-process cache : Map<packageName, { fetchedAt: number, data: object | null }>
+// Negative caching (data === null) is honored too — avoids repeat 404 hammering.
+const _pypiMetadataCache = new Map();
+
+// AbortSignal.timeout polyfill — mirror npm-registry.js
+function createTimeoutSignal(ms) {
+  if (typeof AbortSignal !== 'undefined' && AbortSignal.timeout) {
+    return { signal: AbortSignal.timeout(ms), cleanup: () => {} };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  return { signal: controller.signal, cleanup: () => clearTimeout(timer) };
+}
+
+async function fetchWithRetry(url) {
+  let lastError = null;
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    let response;
+    const { signal, cleanup } = createTimeoutSignal(REQUEST_TIMEOUT);
+    try {
+      response = await fetch(url, { signal });
+    } catch (err) {
+      cleanup();
+      lastError = err;
+      if (attempt < MAX_RETRIES - 1) {
+        const backoff = Math.min(1000 * Math.pow(2, attempt), 8000);
+        await new Promise(r => setTimeout(r, backoff));
+      }
+      continue;
+    }
+    cleanup();
+
+    if (response.status === 404) {
+      try { await response.text(); } catch (e) { debugLog('pypi-registry: response drain failed:', e.message); }
+      return null;
+    }
+
+    if (response.status === 429) {
+      try { await response.text(); } catch (e) { debugLog('pypi-registry: response drain failed:', e.message); }
+      const retryAfter = parseInt(response.headers.get('retry-after'), 10);
+      const delay = Math.min(retryAfter && retryAfter > 0 ? retryAfter * 1000 : 2000, 30000);
+      await new Promise(r => setTimeout(r, delay));
+      continue;
+    }
+
+    if (!response.ok) {
+      try { await response.text(); } catch (e) { debugLog('pypi-registry: response drain failed:', e.message); }
+      return null;
+    }
+
+    try {
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+  if (lastError) debugLog('pypi-registry: retries exhausted for ' + url + ': ' + lastError.message);
+  return null;
+}
+
+/**
+ * Extract a deduped, lowercased list of maintainer emails from PyPI metadata.
+ * PyPI distinguishes `author_email` and `maintainer_email` (top-level strings,
+ * not arrays). Either or both may be present. Some packages list multiple
+ * addresses separated by commas — split on those.
+ */
+function extractMaintainerEmails(infoBlock) {
+  const out = new Set();
+  if (!infoBlock || typeof infoBlock !== 'object') return [];
+  for (const field of ['author_email', 'maintainer_email']) {
+    const raw = infoBlock[field];
+    if (typeof raw !== 'string' || !raw.includes('@')) continue;
+    // Split on commas (PEP 621-style multi-author) and on "Name <email>" wrappers
+    const parts = raw.split(',');
+    for (const part of parts) {
+      const m = part.match(/<([^>]+@[^>]+)>/) || part.match(/([^\s<>]+@[^\s<>]+)/);
+      if (m && m[1].includes('@')) out.add(m[1].toLowerCase().trim());
+    }
+  }
+  return Array.from(out);
+}
+
+/**
+ * Extract per-version publish timestamps from PyPI metadata.
+ * `releases` is an object keyed by version string, each value is an array of
+ * file entries with `upload_time_iso_8601`. Use the earliest upload time per
+ * version (a release may have multiple files for sdist + wheels).
+ */
+function extractReleaseTimes(releases) {
+  if (!releases || typeof releases !== 'object') return {};
+  const out = {};
+  for (const [version, files] of Object.entries(releases)) {
+    if (!Array.isArray(files) || files.length === 0) continue;
+    let earliest = null;
+    for (const f of files) {
+      const t = typeof f === 'object' && f ? (f.upload_time_iso_8601 || f.upload_time) : null;
+      if (typeof t !== 'string') continue;
+      if (earliest === null || t < earliest) earliest = t;
+    }
+    if (earliest) out[version] = earliest;
+  }
+  return out;
+}
+
+/**
+ * Fetch + parse PyPI registry metadata. Returns null on validation fail,
+ * cache hit of a previous null, network fail, or 404.
+ *
+ * Cached for 5 minutes (positive AND negative results).
+ *
+ * @param {string} packageName
+ * @returns {Promise<{
+ *   created_at: string | null,
+ *   latest_release_at: string | null,
+ *   age_days: number | null,
+ *   latest_version: string | null,
+ *   version_count: number,
+ *   maintainer_emails: string[],
+ *   yanked: boolean,
+ *   description: string,
+ *   home_page: string | null,
+ *   project_urls: object | null,
+ *   releases: { [version: string]: string }
+ * } | null>}
+ */
+async function getPyPIPackageMetadata(packageName) {
+  if (typeof packageName !== 'string' || !PYPI_PACKAGE_REGEX.test(packageName)) return null;
+  const normalized = packageName.toLowerCase();
+
+  // Cache check (honors negative cache)
+  const cached = _pypiMetadataCache.get(normalized);
+  if (cached && (Date.now() - cached.fetchedAt) < CACHE_TTL) {
+    return cached.data;
+  }
+
+  const url = PYPI_REGISTRY_URL + '/' + encodeURIComponent(packageName) + '/json';
+  let raw;
+  await acquireRegistrySlot();
+  try {
+    raw = await fetchWithRetry(url);
+  } finally {
+    releaseRegistrySlot();
+  }
+
+  if (!raw || typeof raw !== 'object') {
+    _pypiMetadataCache.set(normalized, { fetchedAt: Date.now(), data: null });
+    return null;
+  }
+
+  const info = raw.info || {};
+  const releases = raw.releases || {};
+  const releaseTimes = extractReleaseTimes(releases);
+
+  // earliest + latest publish dates across all release-versions
+  let createdAt = null;
+  let latestReleaseAt = null;
+  for (const t of Object.values(releaseTimes)) {
+    if (createdAt === null || t < createdAt) createdAt = t;
+    if (latestReleaseAt === null || t > latestReleaseAt) latestReleaseAt = t;
+  }
+
+  const ageDays = createdAt
+    ? Math.floor((Date.now() - new Date(createdAt).getTime()) / (1000 * 60 * 60 * 24))
+    : null;
+
+  // Latest version: prefer info.version, fallback to highest key in releases
+  const latestVersion = (typeof info.version === 'string' && info.version) || null;
+
+  // Yanked status of the latest version (PyPI sets a "yanked" boolean on each file).
+  let yanked = false;
+  if (latestVersion && Array.isArray(releases[latestVersion])) {
+    yanked = releases[latestVersion].every(f => f && f.yanked === true);
+  }
+
+  const data = {
+    created_at: createdAt,
+    latest_release_at: latestReleaseAt,
+    age_days: ageDays,
+    latest_version: latestVersion,
+    version_count: Object.keys(releaseTimes).length,
+    maintainer_emails: extractMaintainerEmails(info),
+    yanked,
+    description: typeof info.summary === 'string' ? info.summary
+      : (typeof info.description === 'string' ? info.description.slice(0, 1000) : ''),
+    home_page: typeof info.home_page === 'string' && info.home_page ? info.home_page : null,
+    project_urls: (info.project_urls && typeof info.project_urls === 'object') ? info.project_urls : null,
+    releases: releaseTimes
+  };
+
+  _pypiMetadataCache.set(normalized, { fetchedAt: Date.now(), data });
+  return data;
+}
+
+module.exports = {
+  getPyPIPackageMetadata,
+  // Exposed for unit tests
+  _internal: {
+    PYPI_PACKAGE_REGEX,
+    extractMaintainerEmails,
+    extractReleaseTimes,
+    fetchWithRetry,
+    _pypiMetadataCache,
+    _resetCache: () => _pypiMetadataCache.clear()
+  }
+};

package/src/scanner/pypi-release-zero.js

@@ -0,0 +1,59 @@
+'use strict';
+
+/**
+ * F2-PyPI — Release-Zero detection (PEP 440 variant of release-zero.js).
+ *
+ * Created v2.11.47 to mirror npm's release-zero.js for the PyPI ecosystem.
+ *
+ * Threat model: an attacker publishes a brand-new package with version 0.0.0
+ * (or any 0.x.x variant) as a lure or as a ship-as-vulnerable placeholder.
+ * On its own a v0.x.x is noise (many legit early-stage projects sit there
+ * forever), so we conjunction-gate with `age_days < 30`: a recently-published
+ * 0.x.x is suspicious; an abandoned 0.x.x from 2017 is not.
+ *
+ * PyPI-specific differences vs npm release-zero.js:
+ *  - PEP 440 versions, not semver. We accept 0, 0.1, 0.0.0, 0.1.0a1,
+ *    0.0.0.dev1, 0.1.0rc2, 0.1.0.post1 — anything that starts with "0"
+ *    or "0.0..." in the release/pre/dev segment.
+ *  - No `preinstall`/`postinstall` lifecycle hook concept in PyPI manifests.
+ *    The functionally-equivalent vector — `setup.py cmdclass` override —
+ *    is already covered by PYAST-001. We don't double-detect here.
+ *  - Conjunction is just `recently published` (no script check).
+ */
+
+// Match a PEP 440 "release segment" that is exactly 0 in every component.
+// Accepts: 0 | 0.0 | 0.0.0 | 0.0.0.0
+// Optional pre/post/dev segment: a1 | b2 | rc3 | .dev1 | .post1
+// Also allows the rare epoch prefix `0!` (PEP 440 §epoch).
+const PYPI_RELEASE_ZERO_RE = /^(?:0!)?0(?:\.0)*(?:[abc]\d+|rc\d+|\.dev\d+|\.post\d+)?$/i;
+
+const RECENT_PUBLISH_THRESHOLD_DAYS = 30;
+
+/**
+ * @param {string} version - PyPI version string from registry meta (latest_version).
+ * @param {object} pypiRegistryMeta - { age_days: number | null, ... }.
+ * @returns {object | null} threat object or null.
+ */
+function checkPyPIReleaseZero(version, pypiRegistryMeta) {
+  if (typeof version !== 'string' || version.length === 0) return null;
+  if (!PYPI_RELEASE_ZERO_RE.test(version)) return null;
+  if (!pypiRegistryMeta || typeof pypiRegistryMeta !== 'object') return null;
+
+  const ageDays = pypiRegistryMeta.age_days;
+  if (typeof ageDays !== 'number' || ageDays >= RECENT_PUBLISH_THRESHOLD_DAYS) return null;
+
+  return {
+    type: 'pypi_release_zero',
+    severity: 'MEDIUM',
+    message: 'PyPI package latest version is "' + version + '" (release-zero) and was first published only ' + ageDays + ' day(s) ago — possible lure / ship-as-vulnerable / typosquat-staging pattern. setup.py cmdclass install-time hooks are covered separately by PYAST-001.',
+    file: 'pyproject.toml',
+    count: 1,
+    version,
+    age_days: ageDays
+  };
+}
+
+module.exports = {
+  checkPyPIReleaseZero,
+  _internal: { PYPI_RELEASE_ZERO_RE, RECENT_PUBLISH_THRESHOLD_DAYS }
+};

package/src/scanner/python.js

@@ -433,10 +433,87 @@ function escapeRegex(str) {
   return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/**
+ * Try to detect the NAME of the Python package being scanned. Used by
+ * `pypi-registry.js` to fetch metadata for the scanned package itself.
+ *
+ * Priority order :
+ *  1. pyproject.toml [project] name      (PEP 621)
+ *  2. pyproject.toml [tool.poetry] name
+ *  3. setup.py setup(name="...")
+ *  4. setup.cfg [metadata] name
+ *
+ * Returns null if no canonical name can be extracted.
+ *
+ * @param {string} targetPath
+ * @returns {string | null}
+ */
+function detectScannedPackageName(targetPath) {
+  // Generic helper: extract a section [section_header] up to the next [section]
+  // or end of file. JS regex has no \Z, so we use `(?=\n\[|$)` with no /m flag
+  // on the lookahead anchor.
+  function extractSection(content, header) {
+    // Find [header] line, then capture until the next [ at column 0 or EOF.
+    const startRe = new RegExp('^\\[' + header.replace(/[.[\]\\]/g, '\\$&') + '\\][^\\n]*\\n', 'm');
+    const startMatch = content.match(startRe);
+    if (!startMatch) return null;
+    const start = startMatch.index + startMatch[0].length;
+    const rest = content.slice(start);
+    const nextSection = rest.search(/^\[/m);
+    return nextSection === -1 ? rest : rest.slice(0, nextSection);
+  }
+
+  // 1. pyproject.toml
+  const pyproject = path.join(targetPath, 'pyproject.toml');
+  if (fs.existsSync(pyproject)) {
+    let content;
+    try { content = fs.readFileSync(pyproject, 'utf8'); } catch { content = ''; }
+    // [project] name = "X" — PEP 621
+    const projectSection = extractSection(content, 'project');
+    if (projectSection) {
+      const m = projectSection.match(/^\s*name\s*=\s*["']([^"']+)["']/m);
+      if (m) return m[1].trim();
+    }
+    // [tool.poetry] name = "X"
+    const poetrySection = extractSection(content, 'tool.poetry');
+    if (poetrySection) {
+      const m = poetrySection.match(/^\s*name\s*=\s*["']([^"']+)["']/m);
+      if (m) return m[1].trim();
+    }
+  }
+
+  // 2. setup.py — regex on setup(... name="X" ...). Dotall flag for multi-line args.
+  const setupPy = path.join(targetPath, 'setup.py');
+  if (fs.existsSync(setupPy)) {
+    let content;
+    try { content = fs.readFileSync(setupPy, 'utf8'); } catch { content = ''; }
+    const m = content.match(/\bsetup\s*\(([\s\S]*?)\)/);
+    if (m) {
+      const nameMatch = m[1].match(/\bname\s*=\s*["']([^"']+)["']/);
+      if (nameMatch) return nameMatch[1].trim();
+    }
+  }
+
+  // 3. setup.cfg [metadata] name = X
+  const setupCfg = path.join(targetPath, 'setup.cfg');
+  if (fs.existsSync(setupCfg)) {
+    let content;
+    try { content = fs.readFileSync(setupCfg, 'utf8'); } catch { content = ''; }
+    const metaSection = extractSection(content, 'metadata');
+    if (metaSection) {
+      const m = metaSection.match(/^\s*name\s*=\s*(.+?)\s*$/m);
+      if (m) return m[1].trim();
+    }
+  }
+
+  return null;
+}
+
 module.exports = {
   parseRequirementsTxt,
   parseSetupPy,
   parsePyprojectToml,
   detectPythonProject,
+  detectScannedPackageName,
   normalizePythonName
 };