سلسلة التوريد والـ SBOM: إنت واثق في ألف package ما تعرفهمش؟

01 / ملخص الدرس

الـ code بتاعك ممكن يبقى نضيف، بس node_modules فيه مئات الـ packages من ناس ما تعرفهمش، وأي واحد فيهم بـ postinstall بيقرا الـ env بتاعك ساعة الـ install. بنشغّل package شرير ونشوفه بيسرق، ونفهم typosquatting، و install scripts، و lockfiles و integrity، و SBOM بشكل CycloneDX، و npm audit والـ provenance، و --ignore-scripts، والـ pinning. والتحدي: أداة audit بتقرا الـ lock file وتكشف كل ده وتوقّف الـ CI.

ضمن مسارباك إند Node.js للإنتاج — من تحت الصفر77 / 122

02 / شرح الدرس مكتوبًا

نص شرح المعلم والكود الذي كتبه ونتيجة تشغيله، بنفس ترتيب الدرس.

أهلًا بيك. الدروس اللي فاتت كانت عن الـ code اللي إنت كاتبه. النهارده عن الـ code اللي مش إنت كاتبه. أي مشروع Node فيه package dot json بكام dependency، بس كل dependency ليه dependencies، فبيطلع آخرها node modules فيه مئات، ساعات آلاف الـ packages. وكل واحد فيهم ممكن يحط سطر في الـ scripts اسمه postinstall، بيشتغل أوتوماتيك ساعة ما تعمل npm install، على جهازك، بصلاحياتك، بكل الـ secrets اللي في الـ env. خلّينا نشوف. colorss ده package للمعمل، اسمه قريب من colors الحقيقي. فيه postinstall بيشغّل steal dot js. لما حد يكتب npm install colorss بالغلط بدل colors، أو يعتمد على package تاني بيعتمد عليه، npm بيشغّل الأمر اللي في postinstall، يعني node steal dot js، جُوّه الـ folder بتاع الـ package. فإحنا هنشغّل نفس الأمر بإيدنا، ومعانا اتنين env vars مزيفين بيلعبوا دور الـ secrets بتاعتك. وفي المعمل steal بيطبع بس اللي بيبدأ بـ LAB، علشان ما يطبعش أسرارك الحقيقية.

colorss/steal.js

// steal.js: postinstall شرير (للمعمل). الحقيقي بياخد كل الـ env ويبعتها لـ server بتاع المهاجم.
// هنا بنطبع بس الـ vars اللي بتبدأ بـ LAB_ علشان ما نطبعش أي secret حقيقي عندك
const all = Object.keys(process.env);
const loot = all.filter((k) => k.startsWith("LAB_"));
console.log(`☠ postinstall بتاع colorss اشتغل على جهازك، بصلاحياتك، وشايف ${all.length} env var`);
for (const k of loot) console.log("  ☠ سرقت", k, "=", process.env[k]);
console.log("  ☠ وأقدر أقرا ~/.ssh و ~/.npmrc وأي file عندك");

المخرجات

$ cd colorss && LAB_AWS_SECRET_ACCESS_KEY=lab_fake_123 LAB_GITHUB_TOKEN=ghp_lab_fake node steal.js
☠ postinstall بتاع colorss اشتغل على جهازك، بصلاحياتك، وشايف 11 env var
  ☠ سرقت LAB_AWS_SECRET_ACCESS_KEY = lab_fake_123
  ☠ سرقت LAB_GITHUB_TOKEN = ghp_lab_fake
  ☠ وأقدر أقرا ~/.ssh و ~/.npmrc وأي file عندك

اشتغل، وشاف كل الـ env vars، وسرق الاتنين. الحقيقي كان هياخدهم كلهم، ويقرا الـ SSH keys بتاعتك و npmrc اللي فيه الـ npm token، فيقدر ينشر version شريرة من packages إنت صاحبها. كل ده من غير ما تفتح أي file، بس إنك عملت install. ده حصل في الواقع أكتر من مرة: event stream زمان، و xz utils سنة ألفين أربعة وعشرين، وموجات typosquatting كل كام شهر. والأسوأ: أحيانًا الـ package كان كويس، وبعدين اتباع أو اتهكر الحساب بتاعه، و version جديدة طلعت فيها الـ code الشرير.

طيب نعمل إيه؟ أول حاجة، الـ lockfile. package dot json بيقول express تلاتة أو أجدد، بس package lock dot json بيقول بالضبط أي version، ومن أنهي مصدر، وبـ أي integrity hash. فلو حد غيّر محتوى package على نفس الـ version في الـ registry، الـ hash ما يطابقش والـ install يقف. علشان كده الـ lockfile لازم في git، وفي الـ CI تستخدم npm ci مش npm install: بتعمل install من الـ lock بالضبط، وتقف لو package dot json والـ lock مش متفقين. تاني: install scripts. تقدر تقفلهم كلهم بـ dash dash ignore scripts، وتعمل allowlist للي محتاجينهم فعلًا، زي sharp و esbuild اللي بينزّلوا binaries. تالت: الـ ranges. السقف المفتوح زي الـ star معناه أي version، حتى الشريرة الجاية. اقفل النسخ. رابع: الـ audit. npm audit بيقارن الـ tree بتاعك بـ database فيه الـ vulnerabilities المعروفة.

وحاجة بقت أساسية: الـ SBOM، يعني Software Bill of Materials. ده زي قايمة المكوّنات على علبة الأكل: list بكل package جُوّه اللي بتنشره، بالنسخة والمصدر والـ hash. أشهر شكلين: CycloneDX و SPDX. ليه مهم؟ لما vulnerability جديدة تطلع في package، زي ما حصل في log4j، السؤال الأول بيبقى: إحنا بنستخدمه؟ فين؟ من غير SBOM، بتدوّر أيام. مع SBOM محفوظ لكل release، بتجاوب في دقايق. وبقى في أمريكا وأوروبا متطلب رسمي في تعاقدات كتير. وفيه حاجة أجدد اسمها provenance: npm بقى يقدر يأكّد إن الـ package ده اتبنى فعلًا من الـ commit الفلاني في الـ repo الفلاني، في GitHub Actions، من غير ما حد يلمسه في النص. ده بيقفل نوع كامل من الهجمات. main dot js هي الخطوة اللي هتشتغل في الـ CI قبل أي deploy: بتقرا الـ lock، تطلّع SBOM، تعمل audit بالـ policy بتاعتك، وتوقّف الـ build لو فيه حاجة وحشة. بتستخدم audit dot js اللي هتكتبه. lab lock dot json هو package lock لمحفظة فيها مشاكل مدسوسة، و advisories dot json نسخة صغيرة من database الـ vulnerabilities. التحدي: اكتب audit dot js من غير أي dependency. test dot js فيه أربعة وتلاتين حالة.

تمرين

audit.js: nameOf و cmp (أرقام) و satisfies و distance (Levenshtein) و purl، و buildSbom (CycloneDX)، و audit بيكشف vulnerabilities و install-scripts و source و integrity و typosquat و ranges مفتوحة، و fail على حسب failOn.

الحل. packagesOf بتجمع كل package مرة واحدة لكل name مع version، علشان minimist اللي موجود بنسختين يطلع مرتين في الـ SBOM بس من غير تكرار. cmp بيقارن أرقام، ده مهم: واحد عشرة أكبر من واحد تسعة، والمقارنة كـ string بتقول العكس. distance هي المسافة اللي بتكشف الـ typosquat: colorss على بعد حرف واحد من colors. والـ audit بيلف على كل package وبيجمع الـ findings، والبوابة بتقارن أعلى severity بالـ failOn. نشغّل main dot js.

audit.js

// audit.js: SBOM و audit لـ package-lock.json، من غير أي package (علشان الأداة نفسها ما تبقاش supply chain)

const REGISTRY = "https://registry.npmjs.org/";

// "node_modules/a/node_modules/@s/b" ← "@s/b"
export const nameOf = (path) => path.slice(path.lastIndexOf("node_modules/") + "node_modules/".length);

// "1.2.3" ← [1, 2, 3] (أي prerelease بنتجاهله في المعمل)
const parse = (v) => v.split("-")[0].split(".").map(Number);
export function cmp(a, b) {
  const [x, y] = [parse(a), parse(b)];
  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
  return 0;
}

// ">=8.0.0 <9.0.0": كل الشروط لازم تتحقق
export function satisfies(version, range) {
  return range
    .trim()
    .split(/\s+/)
    .every((c) => {
      const [, op = "=", v] = /^(>=|<=|>|<|=)?(.+)$/.exec(c);
      const r = cmp(version, v);
      return { ">=": r >= 0, "<=": r <= 0, ">": r > 0, "<": r < 0, "=": r === 0 }[op];
    });
}

export const purl = (name, version) => `pkg:npm/${name.replace("@", "%40")}@${version}`;

// عدد الحروف اللي لازم تتغيّر علشان a تبقى b (Levenshtein)
export function distance(a, b) {
  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
  for (let i = 1; i <= a.length; i++) {
    const cur = [i];
    for (let j = 1; j <= b.length; j++)
      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
    prev = cur;
  }
  return prev[b.length];
}

// كل package في الـ lock مرة واحدة لكل name@version، مترتبين
function packagesOf(lock) {
  const seen = new Map();
  for (const [path, p] of Object.entries(lock.packages ?? {})) {
    if (!path) continue; // "" هو المشروع نفسه
    const name = nameOf(path);
    const key = `${name}@${p.version}`;
    if (!seen.has(key)) seen.set(key, { name, path, ...p });
  }
  return [...seen.values()].sort((a, b) => (a.name + a.version).localeCompare(b.name + b.version));
}

// SBOM بشكل CycloneDX: list بكل حاجة جُوّه المشروع
export function buildSbom(lock) {
  return {
    bomFormat: "CycloneDX",
    specVersion: "1.5",
    metadata: { component: { type: "application", name: lock.name, version: lock.version } },
    components: packagesOf(lock).map((p) => {
      const c = { type: "library", name: p.name, version: p.version, purl: purl(p.name, p.version) };
      if (p.integrity?.startsWith("sha512-"))
        c.hashes = [{ alg: "SHA-512", content: Buffer.from(p.integrity.slice(7), "base64").toString("hex") }];
      if (p.dev) c.scope = "optional";
      return c;
    }),
  };
}

const RANK = { low: 1, moderate: 2, high: 3, critical: 4 };

export function audit(lock, advisories, { allowScripts = [], popular = [], failOn = "high" } = {}) {
  const findings = [];
  const add = (kind, pkg, detail, severity) => findings.push({ kind, pkg, detail, severity });

  for (const p of packagesOf(lock)) {
    const id = `${p.name}@${p.version}`;
    for (const a of advisories)
      if (a.package === p.name && satisfies(p.version, a.vulnerable)) add("vulnerability", 
…

المخرجات

$ node main.js
SBOM: 13 component في sbom.json، أول واحد:
  {"type":"library","name":"@acme/logger","version":"2.1.0","purl":"pkg:npm/%40acme/[email protected]"}...

11 مشكلة:
 [high    ] source         @acme/[email protected]     جاي من برّه الـ registry: https://github.com/acme-dev/logger/archive/refs/heads/main.tar.gz
 [high    ] integrity      @acme/[email protected]     مفيش sha512 integrity
 [high    ] vulnerability  [email protected]     GHSA-qwcr-r2fm-qrc7: DoS بـ url encoding
 [high    ] install-script [email protected]          بيشغّل code وقت الـ install
 [critical] typosquat      [email protected]          اسمه قريب أوي من colors
 [critical] typosquat      [email protected]           اسمه قريب أوي من express
 [moderate] vulnerability  [email protected]         GHSA-rv95-896h-c2vc: Open redirect في res.location
 [high    ] vulnerability  [email protected]     GHSA-27h2-hvpr-p74q: مشاكل في verify بتسمح بمفاتيح وalgorithms ضعيفة
 [high    ] vulnerability  [email protected]         GHSA-35jh-r3h4-6jhm: Command injection في template
 [critical] vulnerability  [email protected]         GHSA-xvch-5gv4-984h: Prototype pollution
 [moderate] range          left-pad               range مفتوح: *

⛔ البوابة: الـ buil
…

طلّع الـ SBOM، وكشف حداشر مشكلة: colorss طلع install script و typosquat، و at acme جاي من GitHub مش الـ registry ومن غير integrity، وكام package بـ vulnerabilities، و minimist القديم critical والجديد عدّى، و left pad بـ range مفتوح. والبوابة وقفت الـ build. ونشغّل test dot js.

audit.js

المخرجات

$ node test.js
✅ nameOf عادي 
✅ nameOf nested و scoped 
✅ cmp: 4.17.20 أصغر من 4.17.21 
✅ cmp: 1.10.0 أكبر من 1.9.9 (أرقام مش حروف) 
✅ cmp: متساويين 
✅ satisfies <4.17.21 
✅ satisfies range بشرطين 
✅ satisfies بـ = ومن غير op 
✅ distance colors/colorss ← واحد 
✅ distance express/expres ← واحد 
✅ distance lodash/lodahs ← اتنين 
✅ purl scoped 
✅ SBOM: CycloneDX 1.5 
✅ SBOM: الـ metadata فيه اسم المشروع 
✅ SBOM: تلاتاشر component (minimist بنسختين) 13
✅ SBOM: minimist 1.2.5 و 1.2.8 الاتنين موجودين 
✅ SBOM: lodash فيه purl و SHA-512 hex 
✅ SBOM: @acme/logger من غير hashes 
✅ SBOM: esbuild (dev) scope optional 
✅ SBOM: مفيش المشروع نفسه في الـ components 
✅ lodash 4.17.20 ← vulnerability 
✅ minimist 1.2.5 ← critical، و 1.2.8 ← لأ 
✅ jsonwebtoken و body-parser و express ← vulnerability 
✅ sharp 0.33.5 ← مش vulnerable 
✅ colorss ← install-script، و sharp و esbuild ← لأ (في الـ allowlist) 
✅ colorss و expres ← typosquat 
✅ express نفسه مش typosquat 
✅ @acme/logger ← source و integrity 
✅ left-pad ← range مفتوح 
✅ عدد المشاكل حداشر 11
✅ fail ← true 
✅ lock نضيف ← صفر مشاكل و fail false 
✅ failOn high: حتى لو الـ advisories moderate بس، الـ source بتاع @acme high ← fail 
✅ failOn critical و 
…

كله نجح. في الإنتاج مش هتكتب الأداة دي بإيدك: npm audit و osv scanner و Trivy و Dependabot و Snyk بيعملوا ده وأكتر، و syft بيطلّع SBOM، و Sigstore للـ provenance. بس دلوقتي إنت فاهم كل سطر بيدوّر على إيه. وأهم حاجة اتعلمناها: قلّل عدد الـ dependencies من الأول، كل package بتضيفه هو trust لناس ما تعرفهمش. الدرس الجاي: الـ audit والـ privacy logs. إزاي تسجّل مين عمل إيه، من غير ما تسجّل الباسوردات والـ tokens والـ data الشخصية بالغلط.

main.js

// main.js (ci): الخطوة اللي بتشتغل في الـ CI قبل أي deploy: SBOM + audit + بوابة
import { readFileSync, writeFileSync } from "node:fs";
import { buildSbom, audit } from "./audit.js";

const lock = JSON.parse(readFileSync("lab-lock.json", "utf8")); // package-lock.json بتاع wallet-api
const advisories = JSON.parse(readFileSync("advisories.json", "utf8")); // نسخة صغيرة من GitHub Advisory DB
const policy = {
  allowScripts: ["sharp", "esbuild"], // install scripts راجعناها بإيدنا (بتنزّل binaries)
  popular: ["express", "lodash", "colors", "chalk", "axios", "react", "debug", "commander"],
  failOn: "high",
};

const sbom = buildSbom(lock);
writeFileSync("sbom.json", JSON.stringify(sbom, null, 2));
console.log(`SBOM: ${sbom.components.length} component في sbom.json، أول واحد:`);
console.log(" ", JSON.stringify(sbom.components[0]).slice(0, 110) + "...");

const { findings, fail } = audit(lock, advisories, policy);
console.log(`\n${findings.length} مشكلة:`);
for (const f of findings) console.log(` [${f.severity.padEnd(8)}] ${f.kind.padEnd(14)} ${f.pkg.padEnd(22)} ${f.detail}`);
console.log(fail ? "\n⛔ البوابة: الـ build وقف" : "\n✅ البوابة: عدّى");
process.exitCode = fail ? 1 : 0;

lab-lock.json

{
  "name": "wallet-api",
  "version": "1.4.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "wallet-api",
      "version": "1.4.0",
      "dependencies": {
        "express": "^4.17.1",
        "lodash": "^4.17.20",
        "jsonwebtoken": "^8.5.1",
        "colorss": "^1.0.0",
        "@acme/logger": "^2.0.0",
        "left-pad": "*",
        "sharp": "^0.33.0"
      }
    },
    "node_modules/express": {
      "version": "4.17.1",
      "resolved": "https://registry.npmjs.org/express/-/express-4.17.1.tgz",
      "integrity": "sha512-JRPNGMahRAuo52u8FbfZsIsEpXKbXBByIvFq5PkXGdLIy8HM2Lxk6UPOwIi6RHiaXIODHCMyIEgmYTBuLnDRJA=="
    },
    "node_modules/body-parser": {
      "version": "1.19.0",
      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.19.0.tgz",
      "integrity": "sha512-LauT665A4FDGmh9kRBx8xNj5KneuKDQxwgd4h5cm2rjQAPb064lcwYg22YRyzFkQPCLo6iVXShrS6gQSjenslQ=="
    },
    "node_modules/lodash": {
      "version": "4.17.20",
      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.20.tgz",
      "integrity": "sha512-VLr8BOzv4qBx3Amzcj/ncxG5IpqwyJMOZTZWc8I+Xxzjh4EYm/vn75brvWZizqEtJ+tK1Hy4SVxSjbsQ1Nc2xA=="
    },
    "node_modules/jsonwebtoken": {
      "version": "8.5.1",
      "resolved": "https://registry.npmjs.org/jsonwebtoken/-/jsonwebtoken-8.5.1.tgz",
      "integrity": "sha512-GdeCwFpvUpZou7cIOQUatQyEj4C0GitFNqqrbqdTxoN/P5uaspreUfhWN07APyKlZeTlHY2sDJaYLHqZhJuKoQ=="
    },
    "node_modules/minimist": {
      "version": "1.2.5",
      "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.5.tgz",
      "integrity": "sha512-kinDJTGTxDh+EsFe8FcZrsSwItQBXEGxjm/19cgZO00hvSVEY2f9HDdRCSzaHMAbvJwLIn8YZkyQ0QErflf5sQ=="
    },
    "node_modules/mkdirp/node_modules/minimist": {
      "version": "1.2.8",
      "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
      "integrity": "sha512-ttF12HE9DOuJxz2+Ccr9CGq+HUUPaMrP/BPPRf+xm64N5N9mnvC95RS59KqrvIdQCOSrOf2O3XZZ3O+iK5IPlA=="
    },
    "node_modules/mkdirp": {
      "version": "0.5.6",
      "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.6.tgz",
      "integrity": "sha512-eGFJvxHLZshUGpEWn5a7CmrfPz/YissQSCVAxzTq26qwyflv7uVCzAMEgmC1TYDTwe0OF6vByitTPtl3MyVUzw=="
    },
    "node_modules/colorss": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/colorss/-/colorss-1.0.0.tgz",
      "integrity": "sha512-8ewZJpn3eyzk3ZHkermRNtDn5+1tBzDdnUWVLBN+tDWjCDXd9IjL9D0SJ/5GR1a+ELdHv8XK+bwTrEGrf7xz7A==",
      "hasInstallScript": true
    },
    "node_modules/@acme/logger": {
      "version": "2.1.0",
      "resolved": "https://github.com/acme-dev/logger/archive/refs/heads/main.tar.gz"
    },
    "node_modules/left-pad": {
      "version": "1.3.0",
      "resolved": "https://registry.npmjs.org/left-pad/-/left-pad-1.3.0.tgz",
      "integrity": "sha512-4bNE8iDzkIX8spwnbGvPqBcNlxT5C5EMnT9y6STq4O2KATz0t7YWaSz98MkQGoU9jsbapMReCqTHfYUIL4H4oA=="
    },
    "node_modules/sharp": {
    
…

advisories.json

[
  {
    "id": "GHSA-35jh-r3h4-6jhm",
    "package": "lodash",
    "vulnerable": "<4.17.21",
    "severity": "high",
    "summary": "Command injection في template"
  },
  {
    "id": "GHSA-xvch-5gv4-984h",
    "package": "minimist",
    "vulnerable": "<1.2.6",
    "severity": "critical",
    "summary": "Prototype pollution"
  },
  {
    "id": "GHSA-27h2-hvpr-p74q",
    "package": "jsonwebtoken",
    "vulnerable": ">=0.0.0 <9.0.0",
    "severity": "high",
    "summary": "مشاكل في verify بتسمح بمفاتيح وalgorithms ضعيفة"
  },
  {
    "id": "GHSA-qwcr-r2fm-qrc7",
    "package": "body-parser",
    "vulnerable": "<1.20.3",
    "severity": "high",
    "summary": "DoS بـ url encoding"
  },
  {
    "id": "GHSA-rv95-896h-c2vc",
    "package": "express",
    "vulnerable": "<4.19.2",
    "severity": "moderate",
    "summary": "Open redirect في res.location"
  },
  {
    "id": "GHSA-lab-sharp-old",
    "package": "sharp",
    "vulnerable": ">=0.30.0 <0.32.6",
    "severity": "high",
    "summary": "libwebp heap overflow (نسخة قديمة)"
  }
]

03 / دروس المسار (122)