AikidoSec-safe-chain/docs/troubleshooting.md

Troubleshooting

This guide helps you diagnose and resolve common issues with Aikido Safe Chain.

Verification & Diagnostics

Check Installation

# Check version
safe-chain --version

Verify Shell Integration

Run the verification command for your package manager:

npm safe-chain-verify
pnpm safe-chain-verify

Expected output: `OK: Safe-chain works!`

Test Malware Blocking

Verify that malware detection is working:

npm install safe-chain-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 below.

Logging Options

Use logging flags or environment variables to get more information:

# 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

# 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

2. Clean local installation artifacts:

# Remove node_modules if you want a completely fresh install
rm -rf node_modules

3. Re-test malware blocking:

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:

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:

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:

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.

Important

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

# 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 Shell Integration

# 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:

# 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

npm uninstall -g @aikidosec/safe-chain

Remove Volta Installation

volta uninstall @aikidosec/safe-chain

Remove nvm Installations (All Versions)

# 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

rm -rf ~/.safe-chain