@cyberhub/shieldpm 0.1.0

package/src/monitor/permissions.ts

@@ -0,0 +1,330 @@
+/**
+ * ShieldPM — Permission Manifest System
+ * Defines, loads, validates, and generates shieldpm.json permission manifests.
+ */
+
+import { readFile, writeFile, readdir, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { analyzePackage } from '../analyzer/static.js';
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export interface PackagePermissions {
+  /** Allowed network destinations (glob patterns), or false to block all */
+  net: string[] | false;
+  /** Allowed filesystem paths (relative or absolute), or false to block all */
+  fs: string[] | false;
+  /** Whether native/C++ addons are allowed */
+  native?: boolean;
+  /** Whether child_process spawning is allowed */
+  exec?: boolean;
+  /** Whether environment variable access is allowed */
+  env?: string[] | boolean;
+}
+
+export interface PermissionManifest {
+  /** Manifest format version */
+  version: 1;
+  /** Per-package permission declarations */
+  permissions: Record<string, PackagePermissions>;
+}
+
+export type ResourceType = 'net' | 'fs' | 'native' | 'exec' | 'env';
+
+export interface AccessCheck {
+  allowed: boolean;
+  rule: string;
+  details: string;
+}
+
+// ── Default manifest path ────────────────────────────────────────────────
+
+const MANIFEST_FILENAME = 'shieldpm.json';
+
+function resolveManifestPath(dir?: string): string {
+  return join(dir ?? process.cwd(), MANIFEST_FILENAME);
+}
+
+// ── Load / Save ──────────────────────────────────────────────────────────
+
+/**
+ * Load the permission manifest from disk.
+ */
+export async function loadManifest(dir?: string): Promise<PermissionManifest | null> {
+  const path = resolveManifestPath(dir);
+  try {
+    const raw = await readFile(path, 'utf-8');
+    const parsed = JSON.parse(raw);
+
+    // Basic shape validation
+    if (!parsed.permissions || typeof parsed.permissions !== 'object') {
+      throw new Error('Invalid manifest: missing "permissions" object');
+    }
+
+    return {
+      version: parsed.version ?? 1,
+      permissions: parsed.permissions,
+    };
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null; // No manifest yet
+    }
+    throw err;
+  }
+}
+
+/**
+ * Save a permission manifest to disk.
+ */
+export async function saveManifest(manifest: PermissionManifest, dir?: string): Promise<string> {
+  const path = resolveManifestPath(dir);
+  const json = JSON.stringify(manifest, null, 2) + '\n';
+  await writeFile(path, json, 'utf-8');
+  return path;
+}
+
+// ── Access validation ────────────────────────────────────────────────────
+
+/**
+ * Check whether a package is allowed to access a resource.
+ */
+export function validateAccess(
+  manifest: PermissionManifest,
+  packageName: string,
+  resource: ResourceType,
+  target?: string
+): AccessCheck {
+  const perms = manifest.permissions[packageName];
+
+  // No entry in manifest — default deny
+  if (!perms) {
+    return {
+      allowed: false,
+      rule: 'no-manifest-entry',
+      details: `Package "${packageName}" has no entry in the permission manifest`,
+    };
+  }
+
+  switch (resource) {
+    case 'net': {
+      if (perms.net === false) {
+        return {
+          allowed: false,
+          rule: 'net-blocked',
+          details: `Network access is blocked for "${packageName}"`,
+        };
+      }
+      if (!target) {
+        return {
+          allowed: Array.isArray(perms.net) && perms.net.length > 0,
+          rule: 'net-general',
+          details: Array.isArray(perms.net)
+            ? `Network allowed to: ${perms.net.join(', ')}`
+            : 'Network access not configured',
+        };
+      }
+      // Check target against allowed patterns
+      const allowed = matchesAnyPattern(target, perms.net);
+      return {
+        allowed,
+        rule: allowed ? 'net-allowed' : 'net-denied',
+        details: allowed
+          ? `"${target}" matches allowed network pattern`
+          : `"${target}" does not match any allowed network pattern for "${packageName}"`,
+      };
+    }
+
+    case 'fs': {
+      if (perms.fs === false) {
+        return {
+          allowed: false,
+          rule: 'fs-blocked',
+          details: `Filesystem access is blocked for "${packageName}"`,
+        };
+      }
+      if (!target) {
+        return {
+          allowed: Array.isArray(perms.fs) && perms.fs.length > 0,
+          rule: 'fs-general',
+          details: Array.isArray(perms.fs)
+            ? `FS allowed in: ${perms.fs.join(', ')}`
+            : 'FS access not configured',
+        };
+      }
+      const resolvedTarget = resolve(target);
+      const allowed = perms.fs.some((pattern) => {
+        const resolvedPattern = resolve(pattern);
+        return resolvedTarget.startsWith(resolvedPattern);
+      });
+      return {
+        allowed,
+        rule: allowed ? 'fs-allowed' : 'fs-denied',
+        details: allowed
+          ? `"${target}" is within allowed filesystem paths`
+          : `"${target}" is not within any allowed filesystem path for "${packageName}"`,
+      };
+    }
+
+    case 'native': {
+      const allowed = perms.native === true;
+      return {
+        allowed,
+        rule: allowed ? 'native-allowed' : 'native-denied',
+        details: allowed
+          ? `Native modules allowed for "${packageName}"`
+          : `Native modules blocked for "${packageName}"`,
+      };
+    }
+
+    case 'exec': {
+      const allowed = perms.exec === true;
+      return {
+        allowed,
+        rule: allowed ? 'exec-allowed' : 'exec-denied',
+        details: allowed
+          ? `Process execution allowed for "${packageName}"`
+          : `Process execution blocked for "${packageName}"`,
+      };
+    }
+
+    case 'env': {
+      if (perms.env === false || perms.env === undefined) {
+        return {
+          allowed: false,
+          rule: 'env-blocked',
+          details: `Environment variable access blocked for "${packageName}"`,
+        };
+      }
+      if (perms.env === true) {
+        return {
+          allowed: true,
+          rule: 'env-allowed-all',
+          details: `All environment variables allowed for "${packageName}"`,
+        };
+      }
+      if (!target) {
+        return {
+          allowed: true,
+          rule: 'env-general',
+          details: `Env access allowed for: ${perms.env.join(', ')}`,
+        };
+      }
+      const allowed = perms.env.includes(target);
+      return {
+        allowed,
+        rule: allowed ? 'env-allowed' : 'env-denied',
+        details: allowed
+          ? `Env var "${target}" is allowed for "${packageName}"`
+          : `Env var "${target}" is not allowed for "${packageName}"`,
+      };
+    }
+
+    default:
+      return {
+        allowed: false,
+        rule: 'unknown-resource',
+        details: `Unknown resource type: ${resource}`,
+      };
+  }
+}
+
+// ── Pattern matching ─────────────────────────────────────────────────────
+
+/**
+ * Match a string against an array of glob-like patterns.
+ * Supports: * (any), *.domain.com, exact match.
+ */
+function matchesAnyPattern(value: string, patterns: string[]): boolean {
+  for (const pattern of patterns) {
+    if (pattern === '*') return true;
+
+    // Convert glob pattern to regex
+    const regexStr = pattern
+      .replace(/\./g, '\\.')
+      .replace(/\*/g, '.*');
+    const regex = new RegExp(`^${regexStr}$`, 'i');
+
+    if (regex.test(value)) return true;
+  }
+  return false;
+}
+
+// ── Manifest generation ──────────────────────────────────────────────────
+
+/**
+ * Auto-generate a permission manifest by scanning installed packages.
+ */
+export async function generateManifest(projectDir: string): Promise<PermissionManifest> {
+  const manifest: PermissionManifest = {
+    version: 1,
+    permissions: {},
+  };
+
+  const nodeModules = join(projectDir, 'node_modules');
+  let entries: string[];
+
+  try {
+    entries = await readdir(nodeModules);
+  } catch {
+    return manifest; // No node_modules
+  }
+
+  // Collect package directories (including scoped packages)
+  const packageDirs: { name: string; dir: string }[] = [];
+
+  for (const entry of entries) {
+    if (entry.startsWith('.')) continue;
+
+    const fullPath = join(nodeModules, entry);
+    const entryStat = await stat(fullPath).catch(() => null);
+    if (!entryStat?.isDirectory()) continue;
+
+    if (entry.startsWith('@')) {
+      // Scoped package — look one level deeper
+      const scopedEntries = await readdir(fullPath).catch(() => [] as string[]);
+      for (const scopedEntry of scopedEntries) {
+        const scopedPath = join(fullPath, scopedEntry);
+        const scopedStat = await stat(scopedPath).catch(() => null);
+        if (scopedStat?.isDirectory()) {
+          packageDirs.push({ name: `${entry}/${scopedEntry}`, dir: scopedPath });
+        }
+      }
+    } else {
+      packageDirs.push({ name: entry, dir: fullPath });
+    }
+  }
+
+  // Analyze each package and build permissions
+  for (const { name, dir } of packageDirs) {
+    const report = await analyzePackage(dir);
+
+    const perms: PackagePermissions = {
+      net: false,
+      fs: false,
+    };
+
+    // If the package uses network, allow it (but default to restrictive)
+    if (report.categoryCounts['network']) {
+      perms.net = []; // User must fill in allowed destinations
+    }
+
+    // If the package uses filesystem
+    if (report.categoryCounts['filesystem']) {
+      perms.fs = []; // User must fill in allowed paths
+    }
+
+    // If the package uses child_process
+    if (report.categoryCounts['process']) {
+      perms.exec = false; // Default deny, user opts in
+    }
+
+    // If the package accesses env
+    if (report.categoryCounts['environment']) {
+      perms.env = []; // User must fill in allowed vars
+    }
+
+    manifest.permissions[name] = perms;
+  }
+
+  return manifest;
+}

package/src/sandbox/runner.ts

@@ -0,0 +1,302 @@
+/**
+ * ShieldPM — Sandbox Runner
+ * Executes commands (especially postinstall scripts) in a restricted environment
+ * with network blocking, timeout enforcement, and output capture.
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import { platform } from 'node:os';
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export interface SandboxOptions {
+  /** Working directory for the command */
+  cwd?: string;
+  /** Timeout in milliseconds (default: 30000) */
+  timeout?: number;
+  /** Block network access (default: true) */
+  blockNetwork?: boolean;
+  /** Block environment variables (default: true) */
+  blockEnv?: boolean;
+  /** Allowed environment variable names to pass through */
+  allowedEnvVars?: string[];
+  /** Maximum stdout/stderr size in bytes (default: 1MB) */
+  maxOutputSize?: number;
+  /** Enable verbose logging of sandbox decisions */
+  verbose?: boolean;
+}
+
+export interface SandboxResult {
+  /** Process exit code (null if killed) */
+  exitCode: number | null;
+  /** Captured stdout */
+  stdout: string;
+  /** Captured stderr */
+  stderr: string;
+  /** Warnings generated during execution */
+  warnings: string[];
+  /** Actions that were blocked */
+  blocked: string[];
+  /** Whether the process was killed due to timeout */
+  timedOut: boolean;
+  /** Duration in milliseconds */
+  durationMs: number;
+}
+
+// ── Safe environment builder ─────────────────────────────────────────────
+
+const SAFE_ENV_VARS = new Set([
+  'PATH',
+  'HOME',
+  'USER',
+  'SHELL',
+  'LANG',
+  'LC_ALL',
+  'TERM',
+  'TMPDIR',
+  'TMP',
+  'TEMP',
+  'NODE_ENV',
+  'NODE_PATH',
+]);
+
+const SENSITIVE_ENV_VARS = new Set([
+  'AWS_ACCESS_KEY_ID',
+  'AWS_SECRET_ACCESS_KEY',
+  'AWS_SESSION_TOKEN',
+  'GITHUB_TOKEN',
+  'GH_TOKEN',
+  'NPM_TOKEN',
+  'NPM_AUTH_TOKEN',
+  'DOCKER_PASSWORD',
+  'SSH_AUTH_SOCK',
+  'GPG_TTY',
+  'DATABASE_URL',
+  'REDIS_URL',
+  'API_KEY',
+  'SECRET_KEY',
+  'PRIVATE_KEY',
+]);
+
+function buildSandboxEnv(
+  blockNetwork: boolean,
+  blockEnv: boolean,
+  allowedEnvVars: string[]
+): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  if (blockEnv) {
+    // Only pass through safe variables
+    const allowed = new Set([...SAFE_ENV_VARS, ...allowedEnvVars]);
+    for (const key of allowed) {
+      if (process.env[key] !== undefined) {
+        env[key] = process.env[key]!;
+      }
+    }
+  } else {
+    // Pass through everything except sensitive vars
+    for (const [key, value] of Object.entries(process.env)) {
+      if (!SENSITIVE_ENV_VARS.has(key) && value !== undefined) {
+        env[key] = value;
+      }
+    }
+    // Also pass explicitly allowed
+    for (const key of allowedEnvVars) {
+      if (process.env[key] !== undefined) {
+        env[key] = process.env[key]!;
+      }
+    }
+  }
+
+  // Block network via proxy settings
+  if (blockNetwork) {
+    env['HTTP_PROXY'] = 'http://blocked.shieldpm.local:0';
+    env['HTTPS_PROXY'] = 'http://blocked.shieldpm.local:0';
+    env['http_proxy'] = 'http://blocked.shieldpm.local:0';
+    env['https_proxy'] = 'http://blocked.shieldpm.local:0';
+    env['no_proxy'] = '';
+    env['NODE_OPTIONS'] = [
+      env['NODE_OPTIONS'] ?? '',
+      '--dns-result-order=verbatim',
+    ].filter(Boolean).join(' ');
+  }
+
+  // Prevent spawning of sub-shells from modifying real config
+  env['npm_config_ignore_scripts'] = 'true';
+
+  return env;
+}
+
+// ── Platform-specific restrictions ───────────────────────────────────────
+
+function buildPlatformArgs(): string[] {
+  const args: string[] = [];
+
+  if (platform() === 'linux') {
+    // On Linux, we could use unshare for network namespace isolation
+    // For now, we rely on proxy blocking; future: seccomp/landlock
+  }
+
+  return args;
+}
+
+// ── Output truncation ────────────────────────────────────────────────────
+
+function truncateOutput(output: string, maxSize: number): string {
+  if (Buffer.byteLength(output) <= maxSize) return output;
+
+  const truncated = output.slice(0, maxSize);
+  return truncated + `\n... [output truncated at ${Math.round(maxSize / 1024)}KB]`;
+}
+
+// ── Main runner ──────────────────────────────────────────────────────────
+
+/**
+ * Run a command inside a restricted sandbox environment.
+ */
+export async function runSandboxed(
+  command: string,
+  args: string[] = [],
+  options: SandboxOptions = {}
+): Promise<SandboxResult> {
+  const {
+    cwd = process.cwd(),
+    timeout = 30_000,
+    blockNetwork = true,
+    blockEnv = true,
+    allowedEnvVars = [],
+    maxOutputSize = 1024 * 1024, // 1MB
+    verbose = false,
+  } = options;
+
+  const warnings: string[] = [];
+  const blocked: string[] = [];
+
+  // Build restricted environment
+  const env = buildSandboxEnv(blockNetwork, blockEnv, allowedEnvVars);
+
+  if (blockNetwork) {
+    blocked.push('network: HTTP/HTTPS proxied to blocked endpoint');
+  }
+  if (blockEnv) {
+    const removedCount = Object.keys(process.env).length - Object.keys(env).length;
+    blocked.push(`environment: ${removedCount} env vars stripped`);
+  }
+
+  const startTime = Date.now();
+  let timedOut = false;
+
+  return new Promise<SandboxResult>((resolve) => {
+    let child: ChildProcess;
+    let stdoutChunks: Buffer[] = [];
+    let stderrChunks: Buffer[] = [];
+    let stdoutSize = 0;
+    let stderrSize = 0;
+
+    try {
+      child = spawn(command, args, {
+        cwd,
+        env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        shell: true,
+        // Kill the entire process group on timeout
+        detached: false,
+      });
+    } catch (err) {
+      resolve({
+        exitCode: 1,
+        stdout: '',
+        stderr: `Failed to spawn process: ${err instanceof Error ? err.message : String(err)}`,
+        warnings,
+        blocked,
+        timedOut: false,
+        durationMs: Date.now() - startTime,
+      });
+      return;
+    }
+
+    // Capture stdout
+    child.stdout?.on('data', (chunk: Buffer) => {
+      if (stdoutSize < maxOutputSize) {
+        stdoutChunks.push(chunk);
+        stdoutSize += chunk.length;
+      }
+    });
+
+    // Capture stderr
+    child.stderr?.on('data', (chunk: Buffer) => {
+      if (stderrSize < maxOutputSize) {
+        stderrChunks.push(chunk);
+        stderrSize += chunk.length;
+      }
+
+      // Watch for suspicious patterns in stderr
+      const text = chunk.toString();
+      if (/ECONNREFUSED|ENOTFOUND|blocked\.shieldpm/.test(text)) {
+        warnings.push('Process attempted network access (blocked by sandbox)');
+      }
+    });
+
+    // Timeout
+    const timer = setTimeout(() => {
+      timedOut = true;
+      warnings.push(`Process killed: exceeded ${timeout}ms timeout`);
+      child.kill('SIGKILL');
+    }, timeout);
+
+    // Completion
+    child.on('close', (code) => {
+      clearTimeout(timer);
+
+      const stdout = truncateOutput(Buffer.concat(stdoutChunks).toString('utf-8'), maxOutputSize);
+      const stderr = truncateOutput(Buffer.concat(stderrChunks).toString('utf-8'), maxOutputSize);
+
+      if (code !== 0 && !timedOut) {
+        warnings.push(`Process exited with code ${code}`);
+      }
+
+      resolve({
+        exitCode: code,
+        stdout,
+        stderr,
+        warnings,
+        blocked,
+        timedOut,
+        durationMs: Date.now() - startTime,
+      });
+    });
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      resolve({
+        exitCode: 1,
+        stdout: Buffer.concat(stdoutChunks).toString('utf-8'),
+        stderr: err.message,
+        warnings: [...warnings, `Spawn error: ${err.message}`],
+        blocked,
+        timedOut: false,
+        durationMs: Date.now() - startTime,
+      });
+    });
+
+    // Close stdin immediately
+    child.stdin?.end();
+  });
+}
+
+/**
+ * Run an npm postinstall script in the sandbox.
+ */
+export async function runPostInstall(
+  packageDir: string,
+  script: string,
+  options: SandboxOptions = {}
+): Promise<SandboxResult> {
+  return runSandboxed('sh', ['-c', script], {
+    cwd: packageDir,
+    timeout: 30_000,
+    blockNetwork: true,
+    blockEnv: true,
+    ...options,
+  });
+}

package/src/utils/colors.ts

@@ -0,0 +1,58 @@
+/**
+ * ShieldPM — Terminal color helpers (zero dependencies)
+ * Simple ANSI escape code wrapper, no chalk needed.
+ */
+
+const isColorSupported = (): boolean => {
+  if (process.env.NO_COLOR !== undefined) return false;
+  if (process.env.FORCE_COLOR !== undefined) return true;
+  if (!process.stdout.isTTY) return false;
+  return true;
+};
+
+const enabled = isColorSupported();
+
+const wrap = (open: string, close: string) => {
+  return (text: string): string => {
+    if (!enabled) return text;
+    return `\x1b[${open}m${text}\x1b[${close}m`;
+  };
+};
+
+// Foreground colors
+export const red = wrap('31', '39');
+export const green = wrap('32', '39');
+export const yellow = wrap('33', '39');
+export const blue = wrap('34', '39');
+export const magenta = wrap('35', '39');
+export const cyan = wrap('36', '39');
+export const white = wrap('37', '39');
+export const gray = wrap('90', '39');
+
+// Styles
+export const bold = wrap('1', '22');
+export const dim = wrap('2', '22');
+export const italic = wrap('3', '23');
+export const underline = wrap('4', '24');
+
+// Reset
+export const reset = wrap('0', '0');
+
+// Bright variants
+export const redBright = wrap('91', '39');
+export const greenBright = wrap('92', '39');
+export const yellowBright = wrap('93', '39');
+export const blueBright = wrap('94', '39');
+export const cyanBright = wrap('96', '39');
+
+// Background colors
+export const bgRed = wrap('41', '49');
+export const bgGreen = wrap('42', '49');
+export const bgYellow = wrap('43', '49');
+
+// Composable: bold + color
+export const boldRed = (t: string) => bold(red(t));
+export const boldGreen = (t: string) => bold(green(t));
+export const boldYellow = (t: string) => bold(yellow(t));
+export const boldCyan = (t: string) => bold(cyan(t));
+export const boldBlue = (t: string) => bold(blue(t));