@aikidosec/safe-chain 0.0.1-custom-install-dir

package/docs/shell-integration.md

@@ -0,0 +1,149 @@
+# Shell Integration
+
+## Overview
+
+The shell integration automatically wraps common package manager commands (`npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`, `pip`, `pip3`, `uv`, `uvx`, `poetry`, `pipx`) with Aikido's security scanning functionality. It also intercepts Python module invocations for pip when available: `python -m pip`, `python -m pip3`, `python3 -m pip`, `python3 -m pip3`. This is achieved by sourcing startup scripts that define shell functions to wrap these commands with their Aikido-protected equivalents.
+
+## Supported Shells
+
+Aikido Safe Chain supports integration with the following shells.
+
+| Shell                  | Startup File                 |
+| ---------------------- | ---------------------------- |
+| **Bash**               | `~/.bashrc`                  |
+| **Zsh**                | `~/.zshrc`                   |
+| **Fish**               | `~/.config/fish/config.fish` |
+| **PowerShell Core**    | `$PROFILE`                   |
+| **Windows PowerShell** | `$PROFILE`                   |
+
+## Setup Commands
+
+### Setup Shell Integration
+
+```bash
+safe-chain setup
+```
+
+This command:
+
+- Copies necessary startup scripts to Safe Chain's installation directory (`~/.safe-chain/scripts`)
+- Detects all supported shells on your system
+- Sources each shell's startup file to add Safe Chain functions for `npm`, `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`, `pip`, `pip3`, `uv`, `uvx`, `poetry` and `pipx`
+- Adds lightweight interceptors so `python -m pip[...]` and `python3 -m pip[...]` route through Safe Chain when invoked by name
+
+❗ After running this command, **you must restart your terminal** for the changes to take effect. This ensures that the startup scripts are sourced correctly.
+
+### Remove Shell Integration
+
+```bash
+safe-chain teardown
+```
+
+This command:
+
+- Detects all supported shells on your system
+- Removes the Safe Chain scripts from each shell's startup file, restoring the original commands
+
+❗ After running this command, **you must restart your terminal** to restore the original commands.
+
+## File Locations
+
+The system modifies the following files to source Safe Chain startup scripts:
+
+### Unix/Linux/macOS
+
+- **Bash**: `~/.bashrc`
+- **Zsh**: `~/.zshrc`
+- **Fish**: `~/.config/fish/config.fish`
+- **PowerShell Core**: `$PROFILE` (usually `~/.config/powershell/profile.ps1`)
+
+### Windows
+
+- **PowerShell**: Determined by `$PROFILE` variable
+- **PowerShell Core**: Also determined by `$PROFILE` variable
+
+## Troubleshooting
+
+### Common Issues
+
+**Shell functions not working after setup:**
+
+- Make sure to restart your terminal
+- Check that the startup file was modified to source Safe Chain scripts
+- Check the sourced file exists at `~/.safe-chain/scripts/`
+- Verify your shell is reading the correct startup file
+
+**Getting 'command not found: aikido-npm' error:**
+
+This means the shell functions are working but the Aikido commands aren't installed or available in your PATH:
+
+- Make sure Aikido Safe Chain is properly installed on your system
+- Verify the `aikido-npm`, `aikido-npx`, `aikido-yarn`, `aikido-pnpm`, `aikido-pnpx`, `aikido-bun`, `aikido-bunx`, `aikido-pip`, `aikido-pip3`, `aikido-uv`, `aikido-uvx`, `aikido-poetry` and `aikido-pipx` commands exist
+- Check that these commands are in your system's PATH
+
+### Manual Verification
+
+To verify the integration is working, follow these steps:
+
+1. **Check if startup scripts were sourced in your shell startup file:**
+
+   - **For Bash**: Open `~/.bashrc` in your text editor
+   - **For Zsh**: Open `~/.zshrc` in your text editor
+   - **For Fish**: Open `~/.config/fish/config.fish` in your text editor
+   - **For PowerShell**: Open your PowerShell profile file (run `$PROFILE` in PowerShell to see the path)
+
+   Look for lines that source the Safe Chain startup scripts from `~/.safe-chain/scripts/`
+
+2. **Test that shell functions are active in your terminal:**
+
+   After restarting your terminal, run these commands:
+
+   - `npm --version` - Should show output from the Aikido-wrapped version
+   - `type npm` - Should show that `npm` is a function
+
+3. **If you need to remove the integration manually:**
+
+   Edit the same startup file from step 1 and delete any lines that source Safe Chain scripts from `~/.safe-chain/scripts/`.
+
+## Manual Setup
+
+For advanced users who prefer manual configuration, you can create wrapper functions directly in your shell's startup file. Shell functions take precedence over commands in PATH, so defining an `npm` function will intercept all `npm` calls:
+
+```bash
+# Example for Bash/Zsh
+npm() {
+  if command -v aikido-npm > /dev/null 2>&1; then
+    aikido-npm "$@"
+  else
+    echo "Warning: safe-chain is not installed. npm will run without protection."
+    command npm "$@"
+  fi
+}
+```
+
+Repeat this pattern for `npx`, `yarn`, `pnpm`, `pnpx`, `bun`, `bunx`, `pip`, `pip3`, `uv`, `uvx`, `poetry` and `pipx` using their respective `aikido-*` commands. After adding these functions, restart your terminal to apply the changes.
+
+To intercept Python module invocations for pip without altering Python itself, you can add small forwarding functions:
+
+```bash
+# Example for Bash/Zsh
+python() {
+  if [[ "$1" == "-m" && "$2" == pip* ]]; then
+    local mod="$2"; shift 2
+    if [[ "$mod" == "pip3" ]]; then aikido-pip3 "$@"; else aikido-pip "$@"; fi
+  else
+    command python "$@"
+  fi
+}
+
+python3() {
+  if [[ "$1" == "-m" && "$2" == pip* ]]; then
+    local mod="$2"; shift 2
+    if [[ "$mod" == "pip3" ]]; then aikido-pip3 "$@"; else aikido-pip "$@"; fi
+  else
+    command python3 "$@"
+  fi
+}
+```
+
+Limitations: these only apply when invoking `python`/`python3` by name. Absolute paths (e.g., `/usr/bin/python -m pip`) bypass shell functions.

package/docs/troubleshooting.md

@@ -0,0 +1,321 @@
+# Troubleshooting
+
+This guide helps you diagnose and resolve common issues with Aikido Safe Chain.
+
+## Verification & Diagnostics
+
+### Check Installation
+
+```bash
+# Check version
+safe-chain --version
+```
+
+### Verify Shell Integration
+
+Run the verification command for your package manager:
+
+```bash
+npm safe-chain-verify
+pnpm safe-chain-verify
+pip safe-chain-verify
+uv safe-chain-verify
+
+# Any other supported package manager: {packagemanager} safe-chain-verify
+```
+
+Expected output: `OK: Safe-chain works!`
+
+### Test Malware Blocking
+
+Verify that malware detection is working:
+
+**For JavaScript/Node.js:**
+
+```bash
+npm install safe-chain-test
+```
+
+**For Python:**
+
+```bash
+pip3 install safe-chain-pi-test
+```
+
+These test packages are flagged as malware and should be blocked by Safe Chain.
+
+**If the test package installs successfully instead of being blocked**, see [Malware Not Being Blocked](#malware-not-being-blocked) below.
+
+### Logging Options
+
+Use logging flags or environment variables to get more information:
+
+```bash
+# Verbose mode - detailed diagnostic output for troubleshooting
+npm install express --safe-chain-logging=verbose
+
+# Or set it globally for all commands in your session
+export SAFE_CHAIN_LOGGING=verbose
+npm install express
+
+# Silent mode - suppress all output except malware blocking
+npm install express --safe-chain-logging=silent
+```
+
+## Common Issues
+
+### Malware Not Being Blocked
+
+**Symptom:** Test malware packages (like `safe-chain-test`) install successfully when they should be blocked
+
+**Most Common Cause:** The package is cached in your package manager's local store
+
+Safe-chain blocks malicious packages by intercepting network requests to package registries using its proxy.
+
+When a package is already cached locally, the package manager skips downloading it from the registry, which bypasses the proxy.
+
+**Resolution Steps:**
+
+1. **Clear your package manager's cache:**
+
+   ```bash
+   # For npm
+   npm cache clean --force
+
+   # For pnpm
+   pnpm store prune
+
+   # For yarn (classic)
+   yarn cache clean
+
+   # For yarn (berry/v2+)
+   yarn cache clean --all
+
+   # For bun
+   bun pm cache rm
+   ```
+
+   > **⚠️ Warning:** Cache clearing is safe but will remove all cached packages. Subsequent installations will need to re-download packages. In CI/CD environments or monorepos, this may affect build times.
+
+2. **Clean local installation artifacts:**
+
+   ```bash
+   # Remove node_modules if you want a completely fresh install
+   rm -rf node_modules
+   ```
+
+3. **Re-test malware blocking:**
+
+   ```bash
+   npm install safe-chain-test    # Should be blocked
+   ```
+
+### Shell Aliases Not Working After Installation
+
+**Symptom:** Running `npm` shows regular npm instead of safe-chain wrapped version
+
+**First step:** Restart your terminal (most common fix)
+
+**Verify it's working:**
+
+```bash
+type npm
+```
+
+Should show: `npm is a function`
+
+**If still not working:**
+
+Check that your startup file sources safe-chain scripts from `~/.safe-chain/scripts/`:
+
+- Bash: `~/.bashrc`
+- Zsh: `~/.zshrc`
+- Fish: `~/.config/fish/config.fish`
+- PowerShell: `$PROFILE`
+
+### "Command Not Found: safe-chain"
+
+**Symptom:** Binary not found in PATH
+
+**First step:** Restart your terminal
+
+**Check PATH:**
+
+```bash
+echo $PATH
+```
+
+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
+
+**Steps:**
+
+1. Run `safe-chain teardown` (if binary still exists)
+2. Restart your terminal
+3. If still present, manually edit shell config files:
+   - Bash: `~/.bashrc`
+   - Zsh: `~/.zshrc`
+   - Fish: `~/.config/fish/config.fish`
+   - PowerShell: `$PROFILE`
+4. Remove lines that source scripts from `~/.safe-chain/scripts/`
+5. Restart terminal again
+
+## Manual Verification Steps
+
+### Check Installation Status
+
+```bash
+# Check installation location (helps identify if installed via npm or as standalone binary)
+which safe-chain
+
+# Verify binary exists
+ls ~/.safe-chain/bin/safe-chain
+
+# Check version
+safe-chain --version
+
+# Test shell integration
+type npm
+type pip
+```
+
+**Expected `which` output:**
+
+- Standalone binary (correct): `~/.safe-chain/bin/safe-chain` or `/Users/<username>/.safe-chain/bin/safe-chain`
+- npm global (outdated): path containing `node_modules` or nvm version paths
+
+If `which` shows an npm installation, see [Check for Conflicting Installations](#check-for-conflicting-installations).
+
+### Check Shell Integration
+
+```bash
+# Which shell you're using
+echo $SHELL
+
+# Check if startup file sources safe-chain
+# For Bash:
+grep safe-chain ~/.bashrc
+
+# For Zsh:
+grep safe-chain ~/.zshrc
+
+# For Fish:
+grep safe-chain ~/.config/fish/config.fish
+
+# Verify scripts exist
+ls ~/.safe-chain/scripts/
+```
+
+### Check for Conflicting Installations
+
+> **Note:** The install/uninstall scripts automatically detect and remove conflicting installations, but you can manually check:
+
+```bash
+# Check npm global
+npm list -g @aikidosec/safe-chain
+
+# Check Volta
+volta list safe-chain
+
+# Check nvm (all versions)
+for version in $(nvm list | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+'); do
+  nvm exec "$version" npm list -g @aikidosec/safe-chain 2>/dev/null && echo "Found in $version"
+done
+```
+
+## Manual Cleanup
+
+> **Note:** The install and uninstall scripts automatically handle these cleanup steps. Use these manual commands only if automatic cleanup fails.
+
+### Remove npm Global Installation
+
+```bash
+npm uninstall -g @aikidosec/safe-chain
+```
+
+### Remove Volta Installation
+
+```bash
+volta uninstall @aikidosec/safe-chain
+```
+
+### Remove nvm Installations (All Versions)
+
+```bash
+# Automated approach
+for version in $(nvm list | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+'); do
+  nvm exec "$version" npm uninstall -g @aikidosec/safe-chain
+done
+
+# Or manual per version
+nvm use <version>
+npm uninstall -g @aikidosec/safe-chain
+```
+
+### Clean Shell Configuration Files
+
+Manually remove safe-chain entries from:
+
+- Bash: `~/.bashrc`
+- Zsh: `~/.zshrc`
+- Fish: `~/.config/fish/config.fish`
+- PowerShell: `$PROFILE`
+
+Look for and remove:
+
+- Lines sourcing from `~/.safe-chain/scripts/`
+- Any safe-chain related function definitions
+
+### Remove Installation Directory
+
+```bash
+rm -rf ~/.safe-chain
+```
+
+### Report Issues
+
+If you encounter problems:
+
+1. Visit [GitHub Issues](https://github.com/AikidoSec/safe-chain/issues)
+2. Include:
+   - Operating system and version
+   - Shell type and version
+   - `safe-chain --version` output
+   - Output from verification commands
+   - Verbose logs of the failing command (add the `--safe-chain-logging=verbose` argument)