forged-cli 0.3.8 → 0.4.0

package/README.md

@@ -4,11 +4,12 @@
 
 [![npm version](https://img.shields.io/npm/v/forged-cli?color=00ff41&style=flat-square)](https://www.npmjs.com/package/forged-cli)
 [![downloads](https://img.shields.io/npm/dt/forged-cli?color=00ff41&style=flat-square)](https://www.npmjs.com/package/forged-cli)
+[![tests](https://img.shields.io/github/actions/workflow/status/bkness/forged-cli/test.yml?branch=main&label=tests&color=00ff41&style=flat-square)](https://github.com/bkness/forged-cli/actions/workflows/test.yml)
 [![license](https://img.shields.io/npm/l/forged-cli?color=00ff41&style=flat-square)](https://github.com/bkness/forged-cli)
 
-**Forged** is a modular CLI that builds your shell, automates your workflow, and scans your dependencies. One command to get airborne.
+**Forged** is a CLI toolkit for developers: a dependency security scanner, a credential generator, and a README generator, with shell and workflow tooling on the way.
 
-🌐 **[weballtech.com](https://weballtech.com)** — full docs and feature overview
+🌐 **[weballtech-brandon-kellys-projects.vercel.app](https://weballtech-brandon-kellys-projects.vercel.app/)** — full docs and feature overview
 
 ---
 
@@ -18,50 +19,99 @@
 npm install -g forged-cli
 ```
 
+Requires Node.js 18 or newer. Published from GitHub Actions with [npm provenance](https://docs.npmjs.com/generating-provenance-statements), so every release is traceable to the commit that built it.
+
+---
+
+## Quick Start
+
+```sh
+# Scan a project's dependencies
+forged scan ./my-app
+
+# Generate a strong password
+forged gen pass
+
+# Write a README for the current project
+forged readme
+```
+
 ---
 
-## Features
+## 🔍 Security Scanner
+
+`forged scan [path]` audits every package in your `package-lock.json`:
 
-**🔧 Shell Bootstrap**
-Modular zsh config, plugins, and hooks — ready in minutes.
+- **Known malware** — checked against [OSV.dev](https://osv.dev), including OpenSSF `MAL-` reports and GitHub malware advisories (CWE-506)
+- **Brand-new versions** — flags versions published in the last 72 hours, the window when hijacked releases usually go unnoticed
+- **Tarball integrity** — lockfile hashes vs. the npm registry
+- **Publisher changes** — flags a version published by a different account than the one before it (known maintainer rotations are suppressed)
+- **Typosquats** — names one or two characters away from popular packages
+- **Suspicious install scripts** — `curl | sh`, `eval`, base64 decoding and similar
 
-**🔍 Security Scanner**
-Typosquat detection, tarball integrity, suspicious install scripts.
+```
+Summary: 0 error(s), 1 warning(s), 39 suppressed
+  ℹ  Verified 760 packages against npm registry
+  ℹ  Checked 760 packages against OSV.dev known-malware database
+```
 
-**📁 Project Workflows**
-Auto-detect, boot, and scaffold Node, Python, Rust, and Go projects.
+| Flag | Description |
+|------|-------------|
+| `--verbose`, `-v` | Show suppressed maintainer rotations |
+| `--report` | Save findings to `forged-report.json` |
+| `--report-md` | Save findings to `forged-report.md` |
 
-**🐙 GitHub Dashboard**
-PRs, issues, branches, and repos — all from your terminal.
+**In CI:** `forged scan` exits with code `1` when it finds errors (malware, integrity mismatches, dangerous scripts), so it can fail a build:
+
+```yaml
+- run: npx forged-cli scan
+```
 
 ---
 
-## Commands
+## 🔐 Credential Generator
 
-| Command | Description |
-|---------|-------------|
-| `forged init` | Scaffold a new dev environment |
-| `forged new` | Create a new project with GitHub setup |
-| `forged install` | Install Forged into an existing shell config |
-| `forged scan` | Run security scanner on a project |
-| `forged version` | Show version |
+| Command | Output |
+|---------|--------|
+| `forged gen pass` | 20-character password (upper, lower, digit, symbol) |
+| `forged gen pass --safe` | Password using only `-` and `_` as symbols — router and device friendly |
+| `forged gen pass --length=32` | Custom length (`-l=32` also works) |
+| `forged gen secret` | 32-byte hex secret for JWTs and API keys |
+| `forged gen pin` | 6-digit PIN |
+| `forged gen uuid` | UUID v4 |
+
+Built on Node's `crypto.randomInt`, so every character is chosen uniformly.
 
 ---
 
-## Quick Start
+## 📝 README Generator
 
-```sh
-# Install globally
-npm install -g forged-cli
+`forged readme` asks a few questions and writes a `README.md`, pre-filling your GitHub username, email, and install/test commands from the project (Node, Python, Rust, or Go).
+
+---
 
-# Set up your dev environment
-forged init
+## 🚧 Coming Soon
 
-# Create a new project
-forged new my-app
+These are advertised in `forged help` and currently print "coming soon":
 
-# Scan a project for vulnerabilities
-forged scan ./my-app
+| Command | Plan |
+|---------|------|
+| `forged init` | Set up a modular zsh environment — plugins, hooks, project auto-detection, and a GitHub dashboard |
+| `forged new` | Create a new project with GitHub setup |
+| `forged install` | Add Forged to an existing shell config |
+
+Want them today? They're running in my [dotfiles](https://github.com/bkness/dotfiles).
+
+---
+
+## Development
+
+```sh
+git clone https://github.com/bkness/forged-cli.git
+cd forged-cli
+npm install
+npm test        # node:test, no network needed
+npm link        # use your local copy as the global `forged`
 ```
 
 ---
@@ -72,4 +122,4 @@ MIT © [Brandon Kelly](https://github.com/bkness)
 
 ## Contact
 
-Brandon Kelly — [GitHub](https://github.com/bkness) · [weballtech.com](https://weballtech.com) · kbrandon863@gmail.com
+Brandon Kelly — [GitHub](https://github.com/bkness) · [weballtech-brandon-kellys-projects.vercel.app](https://weballtech-brandon-kellys-projects.vercel.app/) · kbrandon863@gmail.com

package/bin/forged.js

@@ -10,13 +10,17 @@ const { version } = JSON.parse(readFileSync(join(__dirname, '../package.json'),
 const [,, command, ...args] = process.argv;
 
 const commands = {
-  readme:  'Generate a README.md for the current project',
-  scan:    'Audit dependencies for typosquats, bad scripts, and suspicious binaries',
+  scan:    'Audit dependencies — known malware, integrity, publisher changes, typosquats',
   gen:     'Generate passwords, secrets, PINs, and UUIDs',
+  readme:  'Generate a README.md for the current project',
+  version: 'Show Forged version',
+};
+
+// Advertised but not built yet — say so instead of treating them as typos
+const planned = {
   init:    'Scaffold a new dev environment',
   new:     'Create a new project with GitHub setup',
   install: 'Install Forged into an existing shell config',
-  version: 'Show Forged version',
 };
 
 if (!command || command === 'help') {
@@ -28,6 +32,13 @@ if (!command || command === 'help') {
 
   Commands:
 ${Object.entries(commands).map(([cmd, desc]) => `    ${cmd.padEnd(10)} ${desc}`).join('\n')}
+
+  Coming soon:
+${Object.entries(planned).map(([cmd, desc]) => `    ${cmd.padEnd(10)} ${desc}`).join('\n')}
+
+  Scan options:
+    forged scan [path] [--verbose|-v] [--report|--report-md]
+    Exits 1 when errors are found, so it can fail a CI job.
   `);
   process.exit(0);
 }
@@ -55,10 +66,17 @@ if (command === 'scan') {
   const report       = args.includes('--report') || args.includes('--report-md');
   const reportFormat = args.includes('--report-md') ? 'markdown' : 'json';
   const verbose      = args.includes('--verbose') || args.includes('-v');
-  const pathArg      = args.find(a => !a.startsWith('--'));
+  // Any dash-prefixed arg is a flag, not the path (so `-v` isn't scanned as a dir)
+  const pathArg      = args.find(a => !a.startsWith('-'));
   const targetPath   = pathArg ? resolve(pathArg) : process.cwd();
-  await scanCommand(targetPath, { report, reportFormat, verbose });
+  const findings     = await scanCommand(targetPath, { report, reportFormat, verbose });
+  process.exit(findings?.errors.length ? 1 : 0);
+}
+
+if (planned[command]) {
+  console.log(`⚒  Forged — '${command}' is coming soon.`);
   process.exit(0);
 }
 
-console.log(`⚒  Forged — '${command}' coming soon.`);
+console.error(`⚒  Forged — unknown command '${command}'. Run \`forged help\` to see commands.`);
+process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forged-cli",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "description": "A complete dev environment toolkit — shell, workflows, and project scaffolding in one install.",
   "keywords": [
     "cli",
@@ -12,11 +12,10 @@
   ],
   "author": "Brandon <DevBrandon@icloud.com> (https://github.com/bkness)",
   "license": "MIT",
-  "homepage": "https://www.weballtech.com",
+  "homepage": "https://weballtech-brandon-kellys-projects.vercel.app/",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/bkness/forged-cli.git",
-    "directory": "https//www.weballtech.com/manual.html"
+    "url": "git+https://github.com/bkness/forged-cli.git"
   },
   "bugs": {
     "url": "https://github.com/bkness/forged-cli/issues"
@@ -29,7 +28,8 @@
     "node": ">=18"
   },
   "scripts": {
-    "start": "node bin/forged.js"
+    "start": "node bin/forged.js",
+    "test": "node --test"
   },
   "dependencies": {
     "inquirer": "^13.4.2"

package/src/commands/gen.js

@@ -1,4 +1,4 @@
-import { randomBytes, randomUUID } from 'crypto';
+import { randomBytes, randomInt, randomUUID } from 'crypto';
 
 const green  = '\x1b[32m';
 const yellow = '\x1b[33m';
@@ -14,11 +14,13 @@ const DIGITS  = '0123456789';
 const SYMBOLS = '!@#$%^&*()-_=+[]{}|;:,.<>?';
 const SAFE    = '-_';
 
+// randomInt is uniform; `randomBytes(1)[0] % n` over-weights low indexes
+// whenever 256 isn't a multiple of n.
 function randomChar(charset) {
-  return charset[randomBytes(1)[0] % charset.length];
+  return charset[randomInt(charset.length)];
 }
 
-function generatePassword(length, safe = false) {
+export function generatePassword(length, safe = false) {
   const symbols = safe ? SAFE : SYMBOLS;
   const charset = UPPER + LOWER + DIGITS + symbols;
   const required = [
@@ -30,7 +32,7 @@ function generatePassword(length, safe = false) {
   const rest = Array.from({ length: length - required.length }, () => randomChar(charset));
   const all = [...required, ...rest];
   for (let i = all.length - 1; i > 0; i--) {
-    const j = randomBytes(1)[0] % (i + 1);
+    const j = randomInt(i + 1);
     [all[i], all[j]] = [all[j], all[i]];
   }
   return all.join('');
@@ -44,15 +46,27 @@ function colorize(password) {
   }).join('');
 }
 
-function generatePin(length) {
-  return Array.from({ length }, () => randomBytes(1)[0] % 10).join('');
+export function generatePin(length) {
+  return Array.from({ length }, () => randomInt(10)).join('');
+}
+
+// null when no flag given; NaN when the value isn't a whole number
+export function parseLength(args) {
+  const lenArg = args.find(a => /^(-l=|--length=)/.test(a));
+  if (!lenArg) return null;
+  const raw = lenArg.split('=')[1];
+  return /^\d+$/.test(raw) ? Number(raw) : NaN;
 }
 
 export async function genCommand(args) {
   const sub    = args[0];
   const safe   = args.includes('--safe') || args.includes('--ascii');
-  const lenArg = args.find(a => /^(-l=|--length=)/.test(a));
-  const length = lenArg ? parseInt(lenArg.split('=')[1]) : null;
+  const length = parseLength(args);
+
+  if (Number.isNaN(length)) {
+    console.log(`  ${red}--length must be a whole number${reset}`);
+    return;
+  }
 
   if (!sub || sub === 'help') {
     console.log(`
@@ -89,6 +103,7 @@ export async function genCommand(args) {
 
   if (sub === 'pin') {
     const len = length ?? 6;
+    if (len < 1) { console.log(`  ${red}Length must be at least 1${reset}`); return; }
     console.log(`\n  ${bold}PIN${reset}       ${yellow}${generatePin(len)}${reset}\n`);
     return;
   }

package/src/commands/scan.js

@@ -1,10 +1,11 @@
-import { readFileSync, existsSync, readdirSync, statSync, writeFileSync } from 'fs';
+import { readFileSync, existsSync, readdirSync, lstatSync, writeFileSync } from 'fs';
 import { createHash } from 'crypto';
 import { join, basename } from 'path';
 import { homedir } from 'os';
 import { isSuspiciousName } from '../utils/levenshtein.js';
 import { POPULAR_PACKAGES } from '../utils/popularPackages.js';
 import { verifyTarballIntegrity } from '../utils/verifyIntegrity.js';
+import { queryOsv } from '../utils/osv.js';
 
 const green  = '\x1b[32m';
 const yellow = '\x1b[33m';
@@ -12,7 +13,7 @@ const red    = '\x1b[31m';
 const bold   = '\x1b[1m';
 const reset  = '\x1b[0m';
 
-function checkPackageJson(cwd) {
+export function checkPackageJson(cwd) {
   const pkgPath = join(cwd, 'package.json');
   if (!existsSync(pkgPath)) return { deps: {}, error: 'No package.json found' };
   try {
@@ -28,14 +29,16 @@ function checkPackageJson(cwd) {
   }
 }
 
-function scanBinaries(cwd) {
+export function scanBinaries(cwd) {
   const binDir = join(cwd, 'node_modules', '.bin');
   if (!existsSync(binDir)) return [];
   const results = [];
   for (const file of readdirSync(binDir)) {
     const fullPath = join(binDir, file);
     try {
-      const stat = statSync(fullPath);
+      // lstat, not stat: stat follows the link, so isSymbolicLink() was
+      // always false and every large linked binary got flagged
+      const stat = lstatSync(fullPath);
       if (!stat.isSymbolicLink() && stat.size > 50000) {
         results.push({ file, size: stat.size, flag: 'large non-symlink binary' });
       }
@@ -44,7 +47,7 @@ function scanBinaries(cwd) {
   return results;
 }
 
-function checkDangerousScripts(scripts) {
+export function checkDangerousScripts(scripts) {
   const dangerous = [];
   const patterns = [
     /curl\s+.*\|.*sh/,
@@ -58,6 +61,7 @@ function checkDangerousScripts(scripts) {
     for (const pattern of patterns) {
       if (pattern.test(cmd)) {
         dangerous.push({ script: name, command: cmd });
+        break; // one finding per script, even if several patterns match
       }
     }
   }
@@ -147,7 +151,7 @@ export async function scanCommand(cwd = process.cwd(), opts = {}) {
 
   // 4. Tarball integrity verification
   process.stdout.write('   Verifying tarball integrity');
-  const { error: integrityError, findings: integrityFindings, total } = await verifyTarballIntegrity(
+  const { error: integrityError, findings: integrityFindings, total, packages } = await verifyTarballIntegrity(
     cwd,
     (checked, t) => {
       if (checked % 10 === 0 || checked === t) {
@@ -169,6 +173,29 @@ export async function scanCommand(cwd = process.cwd(), opts = {}) {
     if (total) findings.info.push(`Verified ${total} packages against npm registry`);
   }
 
+  // 4b. Known-malware + vulnerability lookup (OSV.dev)
+  if (packages?.length) {
+    const osv = await queryOsv(packages);
+    if (osv === null) {
+      findings.warnings.push({ message: 'Could not reach OSV.dev — skipped known-malware check' });
+    } else {
+      for (const hit of osv) {
+        if (hit.malicious.length) {
+          findings.errors.push({
+            package: hit.name,
+            version: hit.version,
+            message: `KNOWN MALICIOUS PACKAGE (${hit.malicious.join(', ')}) — remove it and rotate any secrets on this machine`,
+          });
+        }
+      }
+      const vulnerable = osv.filter((h) => h.vulns.length).length;
+      findings.info.push(`Checked ${packages.length} packages against OSV.dev known-malware database`);
+      if (vulnerable) {
+        findings.info.push(`${vulnerable} package(s) have published vulnerabilities — run \`npm audit\` for details`);
+      }
+    }
+  }
+
   // 5. Binary scan
   for (const b of scanBinaries(cwd)) {
     findings.warnings.push({
@@ -268,4 +295,6 @@ export async function scanCommand(cwd = process.cwd(), opts = {}) {
 
     console.log(`${green}✔  Report saved: ${reportFile}${reset}\n`);
   }
+
+  return findings;
 }

package/src/utils/freshness.js

@@ -0,0 +1,12 @@
+// Brand-new versions are the riskiest window: hijacked releases are usually
+// caught and unpublished within days, so a version this fresh hasn't had
+// time to be vetted by the community yet.
+export const FRESH_HOURS = 72;
+
+// Returns hours since publish if the version is younger than `hours`, else null
+export function hoursSincePublish(time, version, now = Date.now(), hours = FRESH_HOURS) {
+  const published = Date.parse(time?.[version]);
+  if (Number.isNaN(published)) return null;
+  const age = (now - published) / 3_600_000;
+  return age >= 0 && age < hours ? Math.floor(age) : null;
+}

package/src/utils/osv.js

@@ -0,0 +1,79 @@
+// OSV.dev — Google's open vulnerability database. Known malware shows up two
+// ways: MAL- advisories (OpenSSF malicious-packages project), and GitHub
+// advisories (GHSA-) tagged CWE-506 "Embedded Malicious Code". The batch
+// endpoint only returns ids, so GHSA details are fetched to check the CWE.
+const OSV_BATCH_URL = 'https://api.osv.dev/v1/querybatch';
+const OSV_VULN_URL = 'https://api.osv.dev/v1/vulns/';
+const BATCH_LIMIT = 1000; // OSV's max queries per request
+const DETAIL_CONCURRENCY = 10;
+const MALWARE_CWE = 'CWE-506';
+
+export function isMalwareAdvisory(advisory) {
+  return advisory?.database_specific?.cwe_ids?.includes(MALWARE_CWE) ?? false;
+}
+
+// pkgs: [{ name, version }], results: OSV batch results (same order),
+// malwareIds: Set of non-MAL ids confirmed as malware
+// → [{ name, version, malicious: [ids], vulns: [ids] }] for packages with hits
+export function classifyOsvResults(pkgs, results, malwareIds = new Set()) {
+  const isMalware = (id) => id.startsWith('MAL-') || malwareIds.has(id);
+  return pkgs
+    .map((pkg, i) => {
+      const ids = (results[i]?.vulns ?? []).map((v) => v.id);
+      return {
+        ...pkg,
+        malicious: ids.filter(isMalware),
+        vulns: ids.filter((id) => !isMalware(id)),
+      };
+    })
+    .filter((r) => r.malicious.length || r.vulns.length);
+}
+
+async function findMalwareIds(ids, fetchImpl) {
+  const malware = new Set();
+  const queue = [...ids];
+  const worker = async () => {
+    while (queue.length) {
+      const id = queue.shift();
+      try {
+        const res = await fetchImpl(OSV_VULN_URL + encodeURIComponent(id));
+        if (res.ok && isMalwareAdvisory(await res.json())) malware.add(id);
+      } catch {
+        // detail lookup failed — leave it classified as an ordinary vuln
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: DETAIL_CONCURRENCY }, worker));
+  return malware;
+}
+
+// Returns classified hits, or null if OSV couldn't be reached
+export async function queryOsv(pkgs, fetchImpl = fetch) {
+  const results = [];
+  try {
+    for (let i = 0; i < pkgs.length; i += BATCH_LIMIT) {
+      const chunk = pkgs.slice(i, i + BATCH_LIMIT);
+      const res = await fetchImpl(OSV_BATCH_URL, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          queries: chunk.map(({ name, version }) => ({
+            package: { name, ecosystem: 'npm' },
+            version,
+          })),
+        }),
+      });
+      if (!res.ok) return null;
+      const data = await res.json();
+      results.push(...(data.results ?? []));
+    }
+  } catch {
+    return null;
+  }
+
+  const ghsaIds = new Set(
+    results.flatMap((r) => (r?.vulns ?? []).map((v) => v.id)).filter((id) => !id.startsWith('MAL-')),
+  );
+  const malwareIds = await findMalwareIds(ghsaIds, fetchImpl);
+  return classifyOsvResults(pkgs, results, malwareIds);
+}

package/src/utils/trustedPublishers.js

@@ -57,6 +57,14 @@ export const TRUSTED_COMMUNITY = new Set([
   'jcrugzz',
   // prebuild-install: known npm ecosystem contributor, took over from lovell
   'vweevers',
+  // Expo core team (bot → human publisher rotations)
+  'brentvatne', 'alanhughes', 'kudochien', 'philpl',
+  // Software Mansion team (React Native Reanimated / Screens / Worklets)
+  'kmag', 'matipl01', 'tjzel', 'kkafar',
+  // MongoDB Node.js driver team org (replaced addaleax)
+  'dbx-node',
+  // Meta/Flow official team org (replaced gkz)
+  'flowtype',
 ]);
 
 export function classifyPublisherChange(from, to) {

package/src/utils/verifyIntegrity.js

@@ -1,6 +1,7 @@
 import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { classifyPublisherChange } from './trustedPublishers.js';
+import { hoursSincePublish, FRESH_HOURS } from './freshness.js';
 
 // Fetch registry metadata with a simple in-memory cache to avoid duplicate requests
 const registryCache = new Map();
@@ -108,6 +109,17 @@ export async function verifyTarballIntegrity(cwd, onProgress) {
         return;
       }
 
+      // Brand-new versions haven't been vetted yet — the usual window for hijacks
+      const ageHours = hoursSincePublish(registryMeta.time, meta.version);
+      if (ageHours !== null) {
+        findings.push({
+          type: 'warning',
+          package: name,
+          version: meta.version,
+          message: `Published ${ageHours}h ago — versions under ${FRESH_HOURS}h old haven't been vetted yet`,
+        });
+      }
+
       // Check if the author/publisher changed in this version vs the previous one
       const versions = Object.keys(registryMeta.versions || {});
       const idx = versions.indexOf(meta.version);
@@ -128,5 +140,9 @@ export async function verifyTarballIntegrity(cwd, onProgress) {
     }));
   }
 
-  return { error: null, findings, total: entries.length };
+  const scanned = entries.map(([pkgPath, meta]) => ({
+    name: pkgPath.replace(/^.*node_modules\//, ''),
+    version: meta.version,
+  }));
+  return { error: null, findings, total: entries.length, packages: scanned };
 }