From e8f993623bceeb11032015cca37be03db6fcb6d6 Mon Sep 17 00:00:00 2001 From: Sander Declerck Date: Tue, 6 Jan 2026 15:48:15 +0100 Subject: [PATCH 1/2] Add troubleshooting docs --- README.md | 4 + docs/npm-to-binary-migration.md | 89 ------------ docs/troubleshooting.md | 248 ++++++++++++++++++++++++++++++++ 3 files changed, 252 insertions(+), 89 deletions(-) delete mode 100644 docs/npm-to-binary-migration.md create mode 100644 docs/troubleshooting.md diff --git a/README.md b/README.md index f08daad..14dc26c 100644 --- a/README.md +++ b/README.md @@ -348,3 +348,7 @@ pipeline { ``` After setup, all subsequent package manager commands in your CI pipeline will automatically be protected by Aikido Safe Chain's malware detection. + +# Troubleshooting + +Having issues? See the [Troubleshooting Guide](https://github.com/AikidoSec/safe-chain/blob/main/docs/troubleshooting.md) for help with common problems. diff --git a/docs/npm-to-binary-migration.md b/docs/npm-to-binary-migration.md deleted file mode 100644 index c29a044..0000000 --- a/docs/npm-to-binary-migration.md +++ /dev/null @@ -1,89 +0,0 @@ -# Migrating from npm global tool to binary installation - -If you previously installed safe-chain as an npm global package, you need to migrate to the binary installation. - -Depending on the version manager you're using, the uninstall process differs: - -### Standard npm (no version manager) - -1. **Clean up shell aliases:** - - ```bash - safe-chain teardown - ``` - -2. **Restart your terminal** - -3. **Uninstall the npm package:** - - ```bash - npm uninstall -g @aikidosec/safe-chain - ``` - -4. **Install the binary version** (see [Installation](https://github.com/AikidoSec/safe-chain/blob/main/README.md#installation)) - -### nvm (Node Version Manager) - -**Important:** nvm installs global packages separately for each Node version, so safe-chain must be uninstalled from each version where it was installed. - -1. **Clean up shell aliases:** - - ```bash - safe-chain teardown - ``` - -2. **Restart your terminal** - -3. **Uninstall from all Node versions:** - - **Option A** - Automated script (recommended): - - ```bash - for version in $(nvm list | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+'); do nvm use $version && npm uninstall -g @aikidosec/safe-chain; done - ``` - - **Option B** - Manual per version: - - ```bash - nvm use - npm uninstall -g @aikidosec/safe-chain - ``` - - Repeat for each Node version where safe-chain was installed. - -4. **Install the binary version** (see [Installation](https://github.com/AikidoSec/safe-chain/blob/main/README.md#installation)) - -### Volta - -1. **Clean up shell aliases:** - - ```bash - safe-chain teardown - ``` - -2. **Restart your terminal** - -3. **Uninstall the Volta package:** - - ```bash - volta uninstall @aikidosec/safe-chain - ``` - -4. **Install the binary version** (see [Installation](https://github.com/AikidoSec/safe-chain/blob/main/README.md#installation)) - -## Troubleshooting - -### Shell aliases still present after migration - -1. Run `safe-chain teardown` (if the binary is installed) -2. Manually remove any safe-chain entries from your shell config files: - - Bash: `~/.bashrc` - - Zsh: `~/.zshrc` - - Fish: `~/.config/fish/config.fish` - - PowerShell: `$PROFILE` -3. Restart your terminal -4. Re-run the install script - -### "command not found: safe-chain" after migration - -The binary installation directory (`~/.safe-chain/bin`) may not be in your PATH. Restart your terminal. If the problem persists: re-run the installation of safe-chain. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..0e95f56 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,248 @@ +# 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. + +### Logging Options + +Use logging flags to get more information: + +```bash +# Verbose mode - detailed diagnostic output for troubleshooting +npm install express --safe-chain-logging=verbose + +# Silent mode - suppress all output except malware blocking +npm install express --safe-chain-logging=silent +``` + +## Common Issues + +### 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 + +### 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//.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 + +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 +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 +``` + +## Getting More Information + +### Enable Verbose Logging + +Get detailed diagnostic output: + +```bash +npm install express --safe-chain-logging=verbose +pip install requests --safe-chain-logging=verbose +``` + +### 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 From 504b3ca596ae50f747088e0bab524c7824ce1169 Mon Sep 17 00:00:00 2001 From: Sander Declerck Date: Tue, 6 Jan 2026 16:04:15 +0100 Subject: [PATCH 2/2] Update Conflicting Installations note --- docs/troubleshooting.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 0e95f56..398ef4a 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -133,6 +133,7 @@ type pip ``` **Expected `which` output:** + - Standalone binary (correct): `~/.safe-chain/bin/safe-chain` or `/Users//.safe-chain/bin/safe-chain` - npm global (outdated): path containing `node_modules` or nvm version paths @@ -160,7 +161,7 @@ ls ~/.safe-chain/scripts/ ### Check for Conflicting Installations -The install/uninstall scripts automatically detect and remove conflicting installations, but you can manually check: +> **Note:** The install/uninstall scripts automatically detect and remove conflicting installations, but you can manually check: ```bash # Check npm global