@aikidosec/safe-chain 1.4.2 → 1.4.4

package/README.md

@@ -66,7 +66,6 @@ You can find all available versions on the [releases page](https://github.com/Ai
 ### Verify the installation
 
 1. **❗Restart your terminal** to start using the Aikido Safe Chain.
-
    - This step is crucial as it ensures that the shell aliases for npm, npx, yarn, pnpm, pnpx, bun, bunx, pip, pip3, poetry, uv and pipx are loaded correctly. If you do not restart your terminal, the aliases will not be available.
 
 2. **Verify the installation** by running the verification command:
@@ -159,7 +158,6 @@ You can control the output from Aikido Safe Chain using the `--safe-chain-loggin
 You can set the logging level through multiple sources (in order of priority):
 
 1. **CLI Argument** (highest priority):
-
    - `--safe-chain-logging=silent` - Suppresses all Aikido Safe Chain output except when malware is blocked. The package manager output is written to stdout as normal, and Safe Chain only writes a short message if it has blocked malware and causes the process to exit.
 
      ```shell
@@ -288,6 +286,7 @@ iex "& { $(iwr 'https://github.com/AikidoSec/safe-chain/releases/latest/download
 - ✅ **CircleCI**
 - ✅ **Jenkins**
 - ✅ **Bitbucket Pipelines**
+- ✅ **GitLab Pipelines**
 
 ## GitHub Actions Example
 
@@ -386,14 +385,76 @@ steps:
   - step:
       name: Install
       script:
-        - npm install -g @aikidosec/safe-chain
-        - safe-chain setup-ci
+        - curl -fsSL https://github.com/AikidoSec/safe-chain/releases/latest/download/install-safe-chain.sh | sh -s -- --ci
         - export PATH=~/.safe-chain/shims:$PATH
         - npm ci
 ```
 
 After setup, all subsequent package manager commands in your CI pipeline will automatically be protected by Aikido Safe Chain's malware detection.
 
+## GitLab Pipelines Example
+
+To add safe-chain in GitLab pipelines, you need to install it in the image running the pipeline. This can be done by:
+
+1. Define a dockerfile to run your build
+
+   ```dockerfile
+   FROM node:lts
+
+   # Install safe-chain
+   RUN curl -fsSL https://github.com/AikidoSec/safe-chain/releases/latest/download/install-safe-chain.sh | sh -s -- --ci
+
+   # Add safe-chain to PATH
+   ENV PATH="/root/.safe-chain/shims:/root/.safe-chain/bin:${PATH}"
+   ```
+
+2. Build the Docker image in your CI pipeline
+
+   ```yaml
+   build-image:
+     stage: build-image
+     image: docker:latest
+     services:
+       - docker:dind
+     script:
+       - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
+       - docker build -t $CI_REGISTRY_IMAGE:latest .
+       - docker push $CI_REGISTRY_IMAGE:latest
+   ```
+
+3. Use the image in your pipeline:
+   ```yaml
+   npm-ci:
+     stage: install
+     image: $CI_REGISTRY_IMAGE:latest
+     script:
+       - npm ci
+   ```
+
+The full pipeline for this example looks like this:
+
+```yaml
+stages:
+  - build-image
+  - install
+
+build-image:
+  stage: build-image
+  image: docker:latest
+  services:
+    - docker:dind
+  script:
+    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
+    - docker build -t $CI_REGISTRY_IMAGE:latest .
+    - docker push $CI_REGISTRY_IMAGE:latest
+
+npm-ci:
+  stage: install
+  image: $CI_REGISTRY_IMAGE:latest
+  script:
+    - npm ci
+```
+
 # Troubleshooting
 
-Having issues? See the [Troubleshooting Guide](https://github.com/AikidoSec/safe-chain/blob/main/docs/troubleshooting.md) for help with common problems.
+Having issues? See the [Troubleshooting Guide](https://help.aikido.dev/code-scanning/aikido-malware-scanning/safe-chain-troubleshooting) for help with common problems.

package/bin/safe-chain.js

@@ -63,8 +63,8 @@ if (tool) {
 } else if (command === "setup") {
   setup();
 } else if (command === "teardown") {
-  teardownDirectories();
   teardown();
+  teardownDirectories();
 } else if (command === "setup-ci") {
   setupCi();
 } else if (command === "--version" || command === "-v" || command === "-v") {
@@ -82,36 +82,36 @@ if (tool) {
 
 function writeHelp() {
   ui.writeInformation(
-    chalk.bold("Usage: ") + chalk.cyan("safe-chain <command>")
+    chalk.bold("Usage: ") + chalk.cyan("safe-chain <command>"),
   );
   ui.emptyLine();
   ui.writeInformation(
     `Available commands: ${chalk.cyan("setup")}, ${chalk.cyan(
-      "teardown"
+      "teardown",
     )}, ${chalk.cyan("setup-ci")}, ${chalk.cyan("help")}, ${chalk.cyan(
-      "--version"
-    )}`
+      "--version",
+    )}`,
   );
   ui.emptyLine();
   ui.writeInformation(
     `- ${chalk.cyan(
-      "safe-chain setup"
-    )}: This will setup your shell to wrap safe-chain around npm, npx, yarn, pnpm, pnpx, bun, bunx, pip and pip3.`
+      "safe-chain setup",
+    )}: This will setup your shell to wrap safe-chain around npm, npx, yarn, pnpm, pnpx, bun, bunx, pip and pip3.`,
   );
   ui.writeInformation(
     `- ${chalk.cyan(
-      "safe-chain teardown"
-    )}: This will remove safe-chain aliases from your shell configuration.`
+      "safe-chain teardown",
+    )}: This will remove safe-chain aliases from your shell configuration.`,
   );
   ui.writeInformation(
     `- ${chalk.cyan(
-      "safe-chain setup-ci"
-    )}: This will setup safe-chain for CI environments by creating shims and modifying the PATH.`
+      "safe-chain setup-ci",
+    )}: This will setup safe-chain for CI environments by creating shims and modifying the PATH.`,
   );
   ui.writeInformation(
     `- ${chalk.cyan("safe-chain --version")} (or ${chalk.cyan(
-      "-v"
-    )}): Display the current version of safe-chain.`
+      "-v",
+    )}): Display the current version of safe-chain.`,
   );
   ui.emptyLine();
 }

package/docs/troubleshooting.md

@@ -149,6 +149,37 @@ Should include `~/.safe-chain/bin`
 
 **If persists:** Re-run the installation script
 
+### PowerShell Execution Policy Blocks Scripts (Windows)
+
+**Symptom:** When opening PowerShell, you see an error like:
+
+```
+. : File C:\Users\<username>\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1 cannot be loaded because
+running scripts is disabled on this system.
+CategoryInfo          : SecurityError: (:) [], PSSecurityException
+FullyQualifiedErrorId : UnauthorizedAccess
+```
+
+**Cause:** Windows PowerShell's default execution policy (`Restricted`) blocks all script execution, including safe-chain's initialization script that's sourced from your PowerShell profile.
+
+**Resolution:**
+
+1. **Set the execution policy to allow local scripts:**
+
+   Open PowerShell as Administrator and run:
+
+   ```powershell
+   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
+   ```
+
+   This allows:
+   - Local scripts (like safe-chain's) to run without signing
+   - Downloaded scripts to run only if signed by a trusted publisher
+
+2. **Restart PowerShell** and verify the error is resolved.
+
+> **Note:** `RemoteSigned` is Microsoft's recommended execution policy for client computers. It provides a good balance between security and usability.
+
 ### Shell Aliases Persist After Uninstallation
 
 **Symptom:** safe-chain commands still active after running uninstall script
@@ -277,22 +308,6 @@ Look for and remove:
 rm -rf ~/.safe-chain
 ```
 
-## Getting More Information
-
-### Enable Verbose Logging
-
-Get detailed diagnostic output using a CLI flag or environment variable:
-
-```bash
-# Using CLI flag
-npm install express --safe-chain-logging=verbose
-pip install requests --safe-chain-logging=verbose
-
-# Using environment variable (applies to all commands)
-export SAFE_CHAIN_LOGGING=verbose
-npm install express
-```
-
 ### Report Issues
 
 If you encounter problems:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikidosec/safe-chain",
-  "version": "1.4.2",
+  "version": "1.4.4",
   "scripts": {
     "test": "node --test --experimental-test-module-mocks 'src/**/*.spec.js'",
     "test:watch": "node --test --watch --experimental-test-module-mocks 'src/**/*.spec.js'",
@@ -38,6 +38,7 @@
   "license": "AGPL-3.0-or-later",
   "description": "The Aikido Safe Chain wraps around the [npm cli](https://github.com/npm/cli), [npx](https://github.com/npm/cli/blob/latest/docs/content/commands/npx.md), [yarn](https://yarnpkg.com/), [pnpm](https://pnpm.io/), [pnpx](https://pnpm.io/cli/dlx), [bun](https://bun.sh/), [bunx](https://bun.sh/docs/cli/bunx), [uv](https://docs.astral.sh/uv/) (Python), and [pip](https://pip.pypa.io/) to provide extra checks before installing new packages. This tool will detect when a package contains malware and prompt you to exit, preventing npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, or pip/pip3 from downloading or running the malware.",
   "dependencies": {
+    "archiver": "^7.0.1",
     "certifi": "14.5.15",
     "chalk": "5.4.1",
     "https-proxy-agent": "7.0.6",
@@ -48,6 +49,7 @@
     "semver": "7.7.2"
   },
   "devDependencies": {
+    "@types/archiver": "^7.0.0",
     "@types/ini": "^4.1.1",
     "@types/make-fetch-happen": "^10.0.4",
     "@types/node": "^18.19.130",

package/src/installation/downloadAgent.js

@@ -0,0 +1,125 @@
+import { createWriteStream, createReadStream } from "fs";
+import { createHash } from "crypto";
+import { pipeline } from "stream/promises";
+import fetch from "make-fetch-happen";
+
+const ULTIMATE_VERSION = "v1.0.0";
+
+export const DOWNLOAD_URLS = {
+  win32: {
+    x64: {
+      url: `https://github.com/AikidoSec/safechain-internals/releases/download/${ULTIMATE_VERSION}/SafeChainUltimate-windows-amd64.msi`,
+      checksum:
+        "sha256:c6a36f9b8e55ab6b7e8742cbabc4469d85809237c0f5e6c21af20b36c416ee1d",
+    },
+    arm64: {
+      url: `https://github.com/AikidoSec/safechain-internals/releases/download/${ULTIMATE_VERSION}/SafeChainUltimate-windows-arm64.msi`,
+      checksum:
+        "sha256:46acd1af6a9938ea194c8ee8b34ca9b47c8de22e088a0791f3c0751dd6239c90",
+    },
+  },
+  darwin: {
+    x64: {
+      url: `https://github.com/AikidoSec/safechain-internals/releases/download/${ULTIMATE_VERSION}/SafeChainUltimate-darwin-amd64.pkg`,
+      checksum:
+        "sha256:bb1829e8ca422e885baf37bef08dcbe7df7a30f248e2e89c4071564f7d4f3396",
+    },
+    arm64: {
+      url: `https://github.com/AikidoSec/safechain-internals/releases/download/${ULTIMATE_VERSION}/SafeChainUltimate-darwin-arm64.pkg`,
+      checksum:
+        "sha256:7fe4a785709911cc366d8224b4c290677573b8c4833bd9054768299e55c5f0ed",
+    },
+  },
+};
+
+/**
+ * Builds the download URL for the SafeChain Agent installer.
+ * @param {string} fileName
+ */
+export function getAgentDownloadUrl(fileName) {
+  return `https://github.com/AikidoSec/safechain-internals/releases/download/${ULTIMATE_VERSION}/${fileName}`;
+}
+
+/**
+ * Downloads a file from a URL to a local path.
+ * @param {string} url
+ * @param {string} destPath
+ */
+export async function downloadFile(url, destPath) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Download failed: ${response.statusText}`);
+  }
+  await pipeline(response.body, createWriteStream(destPath));
+}
+
+/**
+ * Returns the current agent version.
+ */
+export function getAgentVersion() {
+  return ULTIMATE_VERSION;
+}
+
+/**
+ * Returns download info (url, checksum) for the current OS and architecture.
+ * @returns {{ url: string, checksum: string } | null}
+ */
+export function getDownloadInfoForCurrentPlatform() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  if (!Object.hasOwn(DOWNLOAD_URLS, platform)) {
+    return null;
+  }
+  const platformUrls =
+    DOWNLOAD_URLS[/** @type {keyof typeof DOWNLOAD_URLS} */ (platform)];
+
+  if (!Object.hasOwn(platformUrls, arch)) {
+    return null;
+  }
+
+  return platformUrls[/** @type {keyof typeof platformUrls} */ (arch)];
+}
+
+/**
+ * Verifies the checksum of a file.
+ * @param {string} filePath
+ * @param {string} expectedChecksum - Format: "algorithm:hash" (e.g., "sha256:abc123...")
+ * @returns {Promise<boolean>}
+ */
+export async function verifyChecksum(filePath, expectedChecksum) {
+  const [algorithm, expected] = expectedChecksum.split(":");
+
+  const hash = createHash(algorithm);
+
+  if (filePath.includes("..")) throw new Error("Invalid file path");
+  const stream = createReadStream(filePath);
+
+  for await (const chunk of stream) {
+    hash.update(chunk);
+  }
+
+  const actual = hash.digest("hex");
+  return actual === expected;
+}
+
+/**
+ * Downloads the SafeChain agent for the current OS/arch and verifies its checksum.
+ * @param {string} fileName - Destination file path
+ * @returns {Promise<string | null>} The file path if successful, null if no download URL for current platform
+ */
+export async function downloadAgentToFile(fileName) {
+  const info = getDownloadInfoForCurrentPlatform();
+  if (!info) {
+    return null;
+  }
+
+  await downloadFile(info.url, fileName);
+
+  const isValid = await verifyChecksum(fileName, info.checksum);
+  if (!isValid) {
+    throw new Error("Checksum verification failed");
+  }
+
+  return fileName;
+}

package/src/installation/installOnMacOS.js

@@ -0,0 +1,155 @@
+import { tmpdir } from "os";
+import { unlinkSync } from "fs";
+import { join } from "path";
+import { execSync, spawnSync } from "child_process";
+import { ui } from "../environment/userInteraction.js";
+import { printVerboseAndSafeSpawn } from "../utils/safeSpawn.js";
+import { downloadAgentToFile, getAgentVersion } from "./downloadAgent.js";
+import chalk from "chalk";
+
+const MACOS_PKG_IDENTIFIER = "com.aikidosecurity.safechainultimate";
+
+/**
+ * Checks if root privileges are available and displays error message if not.
+ * @param {string} command - The sudo command to show in the error message
+ * @returns {boolean} True if running as root, false otherwise.
+ */
+function requireRootPrivileges(command) {
+  if (isRunningAsRoot()) {
+    return true;
+  }
+
+  ui.writeError("Root privileges required.");
+  ui.writeInformation("Please run this command with sudo:");
+  ui.writeInformation(`  ${command}`);
+  return false;
+}
+
+function isRunningAsRoot() {
+  const rootUserUid = 0;
+  return process.getuid?.() === rootUserUid;
+}
+
+export async function installOnMacOS() {
+  if (!requireRootPrivileges("sudo safe-chain ultimate")) {
+    return;
+  }
+
+  const pkgPath = join(tmpdir(), `SafeChainUltimate-${Date.now()}.pkg`);
+
+  ui.emptyLine();
+  ui.writeInformation(`📥 Downloading SafeChain Ultimate ${getAgentVersion()}`);
+  ui.writeVerbose(`Destination: ${pkgPath}`);
+
+  const result = await downloadAgentToFile(pkgPath);
+  if (!result) {
+    ui.writeError("No download available for this platform/architecture.");
+    return;
+  }
+
+  try {
+    ui.writeInformation("⚙️  Installing SafeChain Ultimate...");
+    await runPkgInstaller(pkgPath);
+
+    ui.emptyLine();
+    ui.writeInformation(
+      "✅ SafeChain Ultimate installed and started successfully!",
+    );
+    ui.emptyLine();
+    ui.writeInformation(
+      chalk.cyan("🔐 ") +
+        chalk.bold("ACTION REQUIRED: ") +
+        "macOS will show a popup to install our certificate.",
+    );
+    ui.writeInformation(
+      "   " +
+        chalk.bold("Please accept the certificate") +
+        " to complete the installation.",
+    );
+    ui.emptyLine();
+  } finally {
+    ui.writeVerbose(`Cleaning up temporary file: ${pkgPath}`);
+    cleanup(pkgPath);
+  }
+}
+
+const MACOS_UNINSTALL_SCRIPT =
+  "/Library/Application\\ Support/AikidoSecurity/SafeChainUltimate/scripts/uninstall";
+
+export async function uninstallOnMacOS() {
+  if (!requireRootPrivileges("sudo safe-chain ultimate uninstall")) {
+    return;
+  }
+
+  ui.emptyLine();
+
+  if (!isPackageInstalled()) {
+    ui.writeInformation("SafeChain Ultimate is not installed.");
+    return;
+  }
+
+  ui.writeInformation("🗑️  Uninstalling SafeChain Ultimate...");
+  ui.writeVerbose(`Running: ${MACOS_UNINSTALL_SCRIPT}`);
+
+  const result = spawnSync(MACOS_UNINSTALL_SCRIPT, {
+    stdio: "inherit",
+    shell: true,
+  });
+
+  if (result.status !== 0) {
+    ui.writeError(
+      `Uninstall script failed (exit code: ${result.status}). Please try again or remove manually.`,
+    );
+    return;
+  }
+
+  ui.emptyLine();
+  ui.writeInformation("✅ SafeChain Ultimate has been uninstalled.");
+  ui.emptyLine();
+}
+
+function isPackageInstalled() {
+  try {
+    const output = execSync(`pkgutil --pkg-info ${MACOS_PKG_IDENTIFIER}`, {
+      encoding: "utf8",
+      stdio: "pipe",
+    });
+    return output.includes(MACOS_PKG_IDENTIFIER);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} pkgPath
+ */
+async function runPkgInstaller(pkgPath) {
+  // Uses installer to install the package (https://ss64.com/mac/installer.html)
+  // Options:
+  //  -pkg (required):    The package to be installed.
+  //  -target (required): The target volume is specified with the -target parameter.
+  //                       --> "-target /" installs to the current boot volume.
+
+  const result = await printVerboseAndSafeSpawn(
+    "installer",
+    ["-pkg", pkgPath, "-target", "/"],
+    {
+      stdio: "inherit",
+    },
+  );
+
+  if (result.status !== 0) {
+    throw new Error(`PKG installer failed (exit code: ${result.status})`);
+  }
+}
+
+/**
+ * @param {string} pkgPath
+ */
+function cleanup(pkgPath) {
+  try {
+    unlinkSync(pkgPath);
+  } catch {
+    ui.writeVerbose("Failed to clean up temporary installer file.");
+  }
+}

package/src/installation/installOnWindows.js

@@ -0,0 +1,203 @@
+import { tmpdir } from "os";
+import { unlinkSync } from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+import { ui } from "../environment/userInteraction.js";
+import { printVerboseAndSafeSpawn, safeSpawn } from "../utils/safeSpawn.js";
+import { downloadAgentToFile, getAgentVersion } from "./downloadAgent.js";
+
+const WINDOWS_SERVICE_NAME = "SafeChainUltimate";
+const WINDOWS_APP_NAME = "SafeChain Ultimate";
+
+export async function uninstallOnWindows() {
+  if (!(await requireAdminPrivileges())) {
+    return;
+  }
+
+  ui.emptyLine();
+
+  const productCode = getInstalledProductCode();
+  if (!productCode) {
+    ui.writeInformation("SafeChain Ultimate is not installed.");
+    return;
+  }
+
+  await stopServiceIfRunning();
+
+  ui.writeInformation("🗑️  Uninstalling SafeChain Ultimate...");
+  await uninstallByProductCode(productCode);
+
+  ui.emptyLine();
+  ui.writeInformation("✅ SafeChain Ultimate has been uninstalled.");
+  ui.emptyLine();
+}
+
+export async function installOnWindows() {
+  if (!(await requireAdminPrivileges())) {
+    return;
+  }
+
+  const msiPath = join(tmpdir(), `SafeChainUltimate-${Date.now()}.msi`);
+
+  ui.emptyLine();
+  ui.writeInformation(`📥 Downloading SafeChain Ultimate ${getAgentVersion()}`);
+  ui.writeVerbose(`Destination: ${msiPath}`);
+
+  const result = await downloadAgentToFile(msiPath);
+  if (!result) {
+    ui.writeError("No download available for this platform/architecture.");
+    return;
+  }
+
+  try {
+    ui.emptyLine();
+    await stopServiceIfRunning();
+    await uninstallIfInstalled();
+
+    ui.writeInformation("⚙️  Installing SafeChain Ultimate...");
+    await runMsiInstaller(msiPath);
+
+    ui.emptyLine();
+    ui.writeInformation(
+      "✅ SafeChain Ultimate installed and started successfully!",
+    );
+    ui.emptyLine();
+  } finally {
+    ui.writeVerbose(`Cleaning up temporary file: ${msiPath}`);
+    cleanup(msiPath);
+  }
+}
+
+/**
+ * Checks if admin privileges are available and displays error message if not.
+ * @returns {Promise<boolean>} True if running as admin, false otherwise.
+ */
+async function requireAdminPrivileges() {
+  if (await isRunningAsAdmin()) {
+    return true;
+  }
+
+  ui.writeError("Administrator privileges required.");
+  ui.writeInformation(
+    "Please run this command in an elevated terminal (Run as Administrator).",
+  );
+  return false;
+}
+
+async function isRunningAsAdmin() {
+  // Uses Windows Security API to check if current process has admin privileges.
+  // Returns "True" or "False" as a string.
+  const result = await safeSpawn(
+    "powershell",
+    [
+      "-Command",
+      "([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)",
+    ],
+    { stdio: "pipe" },
+  );
+
+  return result.status === 0 && result.stdout.trim() === "True";
+}
+
+/**
+ * Returns the MSI product code for SafeChain Ultimate, or null if not installed.
+ * @returns {string | null}
+ */
+function getInstalledProductCode() {
+  // Query Win32_Product via WMI to find the installed SafeChain Agent.
+  // If found, outputs the product GUID (e.g., "{12345678-1234-...}") needed for msiexec uninstall.
+  ui.writeVerbose(`Finding product code with PowerShell`);
+
+  let productCode;
+  try {
+    productCode = execSync(
+      `powershell -Command "$app = Get-WmiObject -Class Win32_Product -Filter \\"Name='${WINDOWS_APP_NAME}'\\"; if ($app) { Write-Output $app.IdentifyingNumber }"`,
+      { encoding: "utf8" },
+    ).trim();
+  } catch {
+    return null;
+  }
+  return productCode || null;
+}
+
+/**
+ * @param {string} productCode
+ */
+async function uninstallByProductCode(productCode) {
+  ui.writeVerbose(`Found product code: ${productCode}`);
+
+  // Use msiexec to run the msi installer quitely (https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/msiexec)
+  // Options:
+  //  - /x:         Uninstalls the package.
+  //  - /qn:        Specifies there's no UI during the installation process.
+  //  - /norestart: Stops the device from restarting after the installation completes.
+  const uninstallResult = await printVerboseAndSafeSpawn(
+    "msiexec",
+    ["/x", productCode, "/qn", "/norestart"],
+    { stdio: "inherit" },
+  );
+
+  if (uninstallResult.status !== 0) {
+    throw new Error(`Uninstall failed (exit code: ${uninstallResult.status})`);
+  }
+}
+
+async function uninstallIfInstalled() {
+  const productCode = getInstalledProductCode();
+  if (!productCode) {
+    ui.writeVerbose("No existing installation found (fresh install).");
+    return;
+  }
+
+  ui.writeInformation("🗑️  Removing previous installation...");
+  await uninstallByProductCode(productCode);
+}
+
+/**
+ * @param {string} msiPath
+ */
+async function runMsiInstaller(msiPath) {
+  // Use msiexec to run the msi installer quitely (https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/msiexec)
+  // Options:
+  //  - /i:  Specifies normal installation
+  //  - /qn: Specifies there's no UI during the installation process.
+
+  const result = await printVerboseAndSafeSpawn(
+    "msiexec",
+    ["/i", msiPath, "/qn"],
+    {
+      stdio: "inherit",
+    },
+  );
+
+  if (result.status !== 0) {
+    throw new Error(`MSI installer failed (exit code: ${result.status})`);
+  }
+}
+
+async function stopServiceIfRunning() {
+  ui.writeInformation("⏹️  Stopping running service...");
+
+  const result = await printVerboseAndSafeSpawn(
+    "net",
+    ["stop", WINDOWS_SERVICE_NAME],
+    {
+      stdio: "pipe",
+    },
+  );
+
+  if (result.status !== 0) {
+    ui.writeVerbose("Service not running (will start after installation).");
+  }
+}
+
+/**
+ * @param {string} msiPath
+ */
+function cleanup(msiPath) {
+  try {
+    unlinkSync(msiPath);
+  } catch {
+    ui.writeVerbose("Failed to clean up temporary installer file.");
+  }
+}

package/src/installation/installUltimate.js

@@ -0,0 +1,35 @@
+import { platform } from "os";
+import { ui } from "../environment/userInteraction.js";
+import { initializeCliArguments } from "../config/cliArguments.js";
+import { installOnWindows, uninstallOnWindows } from "./installOnWindows.js";
+import { installOnMacOS, uninstallOnMacOS } from "./installOnMacOS.js";
+
+export async function uninstallUltimate() {
+  initializeCliArguments(process.argv);
+
+  const operatingSystem = platform();
+
+  if (operatingSystem === "win32") {
+    await uninstallOnWindows();
+  } else if (operatingSystem === "darwin") {
+    await uninstallOnMacOS();
+  } else {
+    ui.writeInformation(
+      `Uninstall is not yet supported on ${operatingSystem}.`,
+    );
+  }
+}
+
+export async function installUltimate() {
+  const operatingSystem = platform();
+
+  if (operatingSystem === "win32") {
+    await installOnWindows();
+  } else if (operatingSystem === "darwin") {
+    await installOnMacOS();
+  } else {
+    ui.writeInformation(
+      `${operatingSystem} is not supported yet by SafeChain's ultimate version.`,
+    );
+  }
+}

package/src/main.js

@@ -73,20 +73,20 @@ export async function main(args) {
       ui.writeVerbose(
         `${chalk.green("✔")} Safe-chain: Scanned ${
           auditStats.totalPackages
-        } packages, no malware found.`
+        } packages, no malware found.`,
       );
     }
 
     if (proxy.hasSuppressedVersions()) {
       ui.writeInformation(
         `${chalk.yellow(
-          "ℹ"
-        )} Safe-chain: Some package versions were suppressed due to minimum age requirement.`
+          "ℹ",
+        )} Safe-chain: Some package versions were suppressed due to minimum age requirement.`,
       );
       ui.writeInformation(
         `  To disable this check, use: ${chalk.cyan(
-          "--safe-chain-skip-minimum-package-age"
-        )}`
+          "--safe-chain-skip-minimum-package-age",
+        )}`,
       );
     }
 

package/src/shell-integration/helpers.js

@@ -3,6 +3,8 @@ import * as os from "os";
 import fs from "fs";
 import path from "path";
 import { ECOSYSTEM_JS, ECOSYSTEM_PY } from "../config/settings.js";
+import { safeSpawn } from "../utils/safeSpawn.js";
+import { ui } from "../environment/userInteraction.js";
 
 /**
  * @typedef {Object} AikidoTool
@@ -99,7 +101,7 @@ export const knownAikidoTools = [
     aikidoCommand: "aikido-pipx",
     ecoSystem: ECOSYSTEM_PY,
     internalPackageManagerName: "pipx",
-  }
+  },
   // When adding a new tool here, also update the documentation for the new tool in the README.md
 ];
 
@@ -216,7 +218,13 @@ export function addLineToFile(filePath, line, eol) {
   eol = eol || os.EOL;
 
   const fileContent = fs.readFileSync(filePath, "utf-8");
-  const updatedContent = fileContent + eol + line + eol;
+  let updatedContent = fileContent;
+
+  if (!fileContent.endsWith(eol)) {
+    updatedContent += eol;
+  }
+
+  updatedContent += line + eol;
   fs.writeFileSync(filePath, updatedContent, "utf-8");
 }
 
@@ -237,3 +245,60 @@ function createFileIfNotExists(filePath) {
 
   fs.writeFileSync(filePath, "", "utf-8");
 }
+
+/**
+ * Checks if PowerShell execution policy allows script execution
+ * @param {string} shellExecutableName - The name of the PowerShell executable ("pwsh" or "powershell")
+ * @returns {Promise<{isValid: boolean, policy: string}>} validation result
+ */
+export async function validatePowerShellExecutionPolicy(shellExecutableName) {
+  // Security: Only allow known shell executables
+  const validShells = ["pwsh", "powershell"];
+  if (!validShells.includes(shellExecutableName)) {
+    return { isValid: false, policy: "Unknown" };
+  }
+
+  try {
+    // For Windows PowerShell (5.1), clean PSModulePath to avoid conflicts with PowerShell 7 modules
+    // When safe-chain is invoked from PowerShell 7, it sets its module paths to PSModulePath, causing
+    // Windows PowerShell to try loading incompatible PowerShell 7 modules.
+    // Setting the environment to Windows PowerShell's modules fixes this.
+    let spawnOptions;
+    if (shellExecutableName === "powershell") {
+      const userProfile = process.env.USERPROFILE || "";
+      const cleanPSModulePath = [
+        path.join(userProfile, "Documents", "WindowsPowerShell", "Modules"),
+        "C:\\Program Files\\WindowsPowerShell\\Modules",
+        "C:\\WINDOWS\\system32\\WindowsPowerShell\\v1.0\\Modules",
+      ].join(";");
+
+      spawnOptions = {
+        env: {
+          ...process.env,
+          PSModulePath: cleanPSModulePath,
+        },
+      };
+    } else {
+      spawnOptions = {};
+    }
+
+    const commandResult = await safeSpawn(
+      shellExecutableName,
+      ["-Command", "Get-ExecutionPolicy"],
+      spawnOptions,
+    );
+
+    const policy = commandResult.stdout.trim();
+
+    const acceptablePolicies = ["RemoteSigned", "Unrestricted", "Bypass"];
+    return {
+      isValid: acceptablePolicies.includes(policy),
+      policy: policy,
+    };
+  } catch (err) {
+    ui.writeWarning(
+      `An error happened while trying to find the current executionpolicy in powershell: ${err}`,
+    );
+    return { isValid: false, policy: "Unknown" };
+  }
+}

package/src/shell-integration/setup.js

@@ -1,7 +1,11 @@
 import chalk from "chalk";
 import { ui } from "../environment/userInteraction.js";
 import { detectShells } from "./shellDetection.js";
-import { knownAikidoTools, getPackageManagerList, getScriptsDir } from "./helpers.js";
+import {
+  knownAikidoTools,
+  getPackageManagerList,
+  getScriptsDir,
+} from "./helpers.js";
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
@@ -26,7 +30,7 @@ if (import.meta.url) {
 export async function setup() {
   ui.writeInformation(
     chalk.bold("Setting up shell aliases.") +
-      ` This will wrap safe-chain around ${getPackageManagerList()}.`
+      ` This will wrap safe-chain around ${getPackageManagerList()}.`,
   );
   ui.emptyLine();
 
@@ -42,12 +46,12 @@ export async function setup() {
     ui.writeInformation(
       `Detected ${shells.length} supported shell(s): ${shells
         .map((shell) => chalk.bold(shell.name))
-        .join(", ")}.`
+        .join(", ")}.`,
     );
 
     let updatedCount = 0;
     for (const shell of shells) {
-      if (setupShell(shell)) {
+      if (await setupShell(shell)) {
         updatedCount++;
       }
     }
@@ -58,7 +62,7 @@ export async function setup() {
     }
   } catch (/** @type {any} */ error) {
     ui.writeError(
-      `Failed to set up shell aliases: ${error.message}. Please check your shell configuration.`
+      `Failed to set up shell aliases: ${error.message}. Please check your shell configuration.`,
     );
     return;
   }
@@ -68,12 +72,12 @@ export async function setup() {
  * Calls the setup function for the given shell and reports the result.
  * @param {import("./shellDetection.js").Shell} shell
  */
-function setupShell(shell) {
+async function setupShell(shell) {
   let success = false;
   let error;
   try {
     shell.teardown(knownAikidoTools); // First, tear down to prevent duplicate aliases
-    success = shell.setup(knownAikidoTools);
+    success = await shell.setup(knownAikidoTools);
   } catch (/** @type {any} */ err) {
     success = false;
     error = err;
@@ -82,14 +86,14 @@ function setupShell(shell) {
   if (success) {
     ui.writeInformation(
       `${chalk.bold("- " + shell.name + ":")} ${chalk.green(
-        "Setup successful"
-      )}`
+        "Setup successful",
+      )}`,
     );
   } else {
     ui.writeError(
       `${chalk.bold("- " + shell.name + ":")} ${chalk.red(
-        "Setup failed"
-      )}. Please check your ${shell.name} configuration.`
+        "Setup failed",
+      )}. Please check your ${shell.name} configuration.`,
     );
     if (error) {
       let message = `  Error: ${error.message}`;
@@ -115,11 +119,7 @@ function copyStartupFiles() {
     }
 
     // Use absolute path for source
-    const sourcePath = path.join(
-      dirname,
-      "startup-scripts",
-      file
-    );
+    const sourcePath = path.join(dirname, "startup-scripts", file);
     fs.copyFileSync(sourcePath, targetPath);
   }
 }

package/src/shell-integration/shellDetection.js

@@ -9,7 +9,7 @@ import { ui } from "../environment/userInteraction.js";
  * @typedef {Object} Shell
  * @property {string} name
  * @property {() => boolean} isInstalled
- * @property {(tools: import("./helpers.js").AikidoTool[]) => boolean} setup
+ * @property {(tools: import("./helpers.js").AikidoTool[]) => boolean|Promise<boolean>} setup
  * @property {(tools: import("./helpers.js").AikidoTool[]) => boolean} teardown
  */
 
@@ -28,7 +28,7 @@ export function detectShells() {
     }
   } catch (/** @type {any} */ error) {
     ui.writeError(
-      `We were not able to detect which shells are installed on your system. Please check your shell configuration. Error: ${error.message}`
+      `We were not able to detect which shells are installed on your system. Please check your shell configuration. Error: ${error.message}`,
     );
     return [];
   }

package/src/shell-integration/startup-scripts/init-fish.fish

@@ -71,13 +71,13 @@ end
 
 function printSafeChainWarning
     set original_cmd $argv[1]
-    
+
     # Fish equivalent of ANSI color codes: yellow background, black text for "Warning:"
     set_color -b yellow black
     printf "Warning:"
     set_color normal
     printf " safe-chain is not available to protect you from installing malware. %s will run without it.\n" $original_cmd
-    
+
     # Cyan text for the install command
     printf "Install safe-chain by using "
     set_color cyan
@@ -90,6 +90,20 @@ function wrapSafeChainCommand
     set original_cmd $argv[1]
     set cmd_args $argv[2..-1]
 
+    if not type -fq $original_cmd
+       # If the original command is not available, don't try to wrap it: invoke
+       # it transparently, so the shell can report errors as if this wrapper
+       # didn't exist. fish always adds extra debug information when executing
+       # missing commands from within a function, so after the "command not
+       # found" handler, there will be information about how the
+       # wrapSafeChainCommand function errored out. To avoid users assuming this
+       # is a safe-chain bug, display an explicit error message afterwards.
+       command $original_cmd $cmd_args
+       set oldstatus $status
+       echo "safe-chain tried to run $original_cmd but it doesn't seem to be installed in your \$PATH." >&2
+       return $oldstatus
+    end
+
     if type -q safe-chain
         # If the safe-chain command is available, just run it with the provided arguments
         safe-chain $original_cmd $cmd_args

package/src/shell-integration/startup-scripts/init-posix.sh

@@ -76,6 +76,14 @@ function printSafeChainWarning() {
 function wrapSafeChainCommand() {
   local original_cmd="$1"
 
+  if ! type -f "${original_cmd}" > /dev/null 2>&1; then
+    # If the original command is not available, don't try to wrap it: invoke it
+    # transparently, so the shell can report errors as if this wrapper didn't
+    # exist.
+    command "$@"
+    return $?
+  fi
+
   if command -v safe-chain > /dev/null 2>&1; then
     # If the aikido command is available, just run it with the provided arguments
     safe-chain "$@"

package/src/shell-integration/supported-shells/powershell.js

@@ -2,6 +2,7 @@ import {
   addLineToFile,
   doesExecutableExistOnSystem,
   removeLinesMatchingPattern,
+  validatePowerShellExecutionPolicy,
 } from "../helpers.js";
 import { execSync } from "child_process";
 
@@ -25,25 +26,33 @@ function teardown(tools) {
     // Remove any existing alias for the tool
     removeLinesMatchingPattern(
       startupFile,
-      new RegExp(`^Set-Alias\\s+${tool}\\s+`)
+      new RegExp(`^Set-Alias\\s+${tool}\\s+`),
     );
   }
 
   // Remove the line that sources the safe-chain PowerShell initialization script
   removeLinesMatchingPattern(
     startupFile,
-    /^\.\s+["']?\$HOME[/\\].safe-chain[/\\]scripts[/\\]init-pwsh\.ps1["']?/
+    /^\.\s+["']?\$HOME[/\\].safe-chain[/\\]scripts[/\\]init-pwsh\.ps1["']?/,
   );
 
   return true;
 }
 
-function setup() {
+async function setup() {
+  const { isValid, policy } =
+    await validatePowerShellExecutionPolicy(executableName);
+  if (!isValid) {
+    throw new Error(
+      `PowerShell execution policy is set to '${policy}', which prevents safe-chain from running.\n  -> To fix this, open PowerShell as Administrator and run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned.\n     For more information, see: https://help.aikido.dev/code-scanning/aikido-malware-scanning/safe-chain-troubleshooting#powershell-execution-policy-blocks-scripts-windows`,
+    );
+  }
+
   const startupFile = getStartupFile();
 
   addLineToFile(
     startupFile,
-    `. "$HOME\\.safe-chain\\scripts\\init-pwsh.ps1" # Safe-chain PowerShell initialization script`
+    `. "$HOME\\.safe-chain\\scripts\\init-pwsh.ps1" # Safe-chain PowerShell initialization script`,
   );
 
   return true;
@@ -57,7 +66,7 @@ function getStartupFile() {
     }).trim();
   } catch (/** @type {any} */ error) {
     throw new Error(
-      `Command failed: ${startupFileCommand}. Error: ${error.message}`
+      `Command failed: ${startupFileCommand}. Error: ${error.message}`,
     );
   }
 }

package/src/shell-integration/supported-shells/windowsPowershell.js

@@ -2,6 +2,7 @@ import {
   addLineToFile,
   doesExecutableExistOnSystem,
   removeLinesMatchingPattern,
+  validatePowerShellExecutionPolicy,
 } from "../helpers.js";
 import { execSync } from "child_process";
 
@@ -25,25 +26,33 @@ function teardown(tools) {
     // Remove any existing alias for the tool
     removeLinesMatchingPattern(
       startupFile,
-      new RegExp(`^Set-Alias\\s+${tool}\\s+`)
+      new RegExp(`^Set-Alias\\s+${tool}\\s+`),
     );
   }
 
   // Remove the line that sources the safe-chain PowerShell initialization script
   removeLinesMatchingPattern(
     startupFile,
-    /^\.\s+["']?\$HOME[/\\].safe-chain[/\\]scripts[/\\]init-pwsh\.ps1["']?/
+    /^\.\s+["']?\$HOME[/\\].safe-chain[/\\]scripts[/\\]init-pwsh\.ps1["']?/,
   );
 
   return true;
 }
 
-function setup() {
+async function setup() {
+  const { isValid, policy } =
+    await validatePowerShellExecutionPolicy(executableName);
+  if (!isValid) {
+    throw new Error(
+      `PowerShell execution policy is set to '${policy}', which prevents safe-chain from running.\n  -> To fix this, open PowerShell as Administrator and run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned.\n     For more information, see: https://help.aikido.dev/code-scanning/aikido-malware-scanning/safe-chain-troubleshooting#powershell-execution-policy-blocks-scripts-windows`,
+    );
+  }
+
   const startupFile = getStartupFile();
 
   addLineToFile(
     startupFile,
-    `. "$HOME\\.safe-chain\\scripts\\init-pwsh.ps1" # Safe-chain PowerShell initialization script`
+    `. "$HOME\\.safe-chain\\scripts\\init-pwsh.ps1" # Safe-chain PowerShell initialization script`,
   );
 
   return true;
@@ -57,7 +66,7 @@ function getStartupFile() {
     }).trim();
   } catch (/** @type {any} */ error) {
     throw new Error(
-      `Command failed: ${startupFileCommand}. Error: ${error.message}`
+      `Command failed: ${startupFileCommand}. Error: ${error.message}`,
     );
   }
 }

package/src/ultimate/ultimateTroubleshooting.js

@@ -0,0 +1,111 @@
+import { platform } from 'os';
+import { ui } from "../environment/userInteraction.js";
+import { readFileSync, existsSync } from "node:fs";
+import {randomUUID} from "node:crypto";
+import {createWriteStream} from "fs";
+import archiver from 'archiver';
+import path from "node:path";
+
+export async function printUltimateLogs() {
+  const { proxyLogPath, ultimateLogPath, proxyErrLogPath, ultimateErrLogPath } = getPathsPerPlatform();
+
+  await printLogs(
+    "SafeChain Proxy",
+    proxyLogPath,
+    proxyErrLogPath
+  );
+
+  await printLogs(
+    "SafeChain Ultimate",
+    ultimateLogPath,
+    ultimateErrLogPath
+  );
+}
+
+export async function troubleshootingExport() {
+  const { logDir } = getPathsPerPlatform();
+  return new Promise((resolve, reject) => {
+    if (!existsSync(logDir)) {
+      ui.writeError(`Log directory not found: ${logDir}`);
+      reject(new Error(`Log directory not found: ${logDir}`));
+      return;
+    }
+
+    const date = new Date().toISOString().split('T')[0];
+    const uuid = randomUUID();
+    const zipFileName = `safechain-ultimate-${date}-${uuid}.zip`;
+    const output = createWriteStream(zipFileName);
+    const archive = archiver('zip', { zlib: { level: 9 } });
+
+    output.on('close', () => {
+      ui.writeInformation(`Logs collected and zipped as: ${path.resolve(zipFileName)}`);
+      resolve(zipFileName);
+    });
+
+    archive.on('error', (err) => {
+      ui.writeError(`Failed to zip logs: ${err.message}`);
+      reject(err);
+    });
+
+    archive.pipe(output);
+    archive.directory(logDir, false);
+    archive.finalize();
+  });
+}
+
+
+function getPathsPerPlatform() {
+  const os = platform();
+  if (os === 'win32') {
+    const logDir = `C:\\ProgramData\\AikidoSecurity\\SafeChainUltimate\\logs`;
+    return {
+      logDir,
+      proxyLogPath: `${logDir}\\SafeChainProxy.log`,
+      ultimateLogPath: `${logDir}\\SafeChainUltimate.log`,
+      proxyErrLogPath: `${logDir}\\SafeChainProxy.err`,
+      ultimateErrLogPath: `${logDir}\\SafeChainUltimate.err`,
+    };
+  } else if (os === 'darwin') {
+    const logDir = `/Library/Logs/AikidoSecurity/SafeChainUltimate`;
+    return {
+      logDir,
+      proxyLogPath: `${logDir}/safechain-proxy.log`,
+      ultimateLogPath: `${logDir}/safechain-ultimate.log`,
+      proxyErrLogPath: `${logDir}/safechain-proxy.error.log`,
+      ultimateErrLogPath: `${logDir}/safechain-ultimate.error.log`,
+    };
+  } else {
+    throw new Error('Unsupported platform for log printing.');
+  }
+}
+
+/**
+ * @param {string} appName
+ * @param {string} logPath
+ * @param {string} errLogPath
+ */
+async function printLogs(appName, logPath, errLogPath) {
+  ui.writeInformation(`=== ${appName} Logs ===`);
+  try {
+    if (existsSync(logPath)) {
+      const logs = readFileSync(logPath, "utf-8");
+      ui.writeInformation(logs);
+    } else {
+      ui.writeWarning(`${appName} log file not found: ${logPath}`);
+    }
+  } catch (error) {
+    ui.writeError(`Failed to read ${appName} logs: ${error}`);
+  }
+
+  ui.writeInformation(`=== ${appName} Error Logs ===`);
+  try {
+    if (existsSync(errLogPath)) {
+      const errLogs = readFileSync(errLogPath, "utf-8");
+      ui.writeInformation(errLogs);
+    } else {
+      ui.writeInformation(`No error log file found for ${appName}.`);
+    }
+  } catch (error) {
+    ui.writeError(`Failed to read ${appName} error logs: ${error}`);
+  }
+}

package/src/utils/safeSpawn.js

@@ -1,5 +1,6 @@
 import { spawn, execSync } from "child_process";
 import os from "os";
+import { ui } from "../environment/userInteraction.js";
 
 /**
  * @param {string} arg
@@ -135,3 +136,18 @@ export async function safeSpawn(command, args, options = {}) {
     });
   });
 }
+
+/**
+ * @param {string} command
+ * @param {string[]} args
+ * @param {import("child_process").SpawnOptions} options
+ *
+ * @returns {Promise<{status: number, stdout: string, stderr: string}>}
+ */
+export async function printVerboseAndSafeSpawn(command, args, options = {}) {
+  ui.writeVerbose(`Running: ${command} ${args.join(" ")}`);
+
+  const result = await safeSpawn(command, args, options);
+
+  return result;
+}