@kilopal/gasha

🛡️ Gasha — Defense-first Package Manager

Gasha is a next-generation secure package manager that protects both package publishers and consumers from supply chain attacks through cryptographic verification, sandboxed installations, and AI-powered security auditing.

🎯 Why Gasha?

The npm ecosystem faces growing security threats:

• Supply chain attacks (malicious packages, typosquatting)
• Postinstall scripts that can execute arbitrary code
• Dependency confusion attacks
• Lack of package integrity verification
• No transparency in package origins

Gasha solves these problems with defense-in-depth security.

🔒 How Gasha Works

For Package Consumers (Installing Packages)

When you install a package with Gasha, it performs these security checks:

• 🔍 SHA256 Verification - Ensures package integrity hasn't been tampered with
• 🔐 Cryptographic Verification - Verifies package signatures (if available)
• 🛡️ Security Audit - Scans for suspicious patterns and risky code
• 📦 Sandboxed Extraction - Safely extracts packages in isolated Docker containers
• 📊 AI Analysis - Optional AI-powered risk assessment

For Package Publishers (Publishing Packages)

When you publish a package with Gasha, it provides:

• 🔑 Key Generation - Creates cryptographic keypairs (RSA/Ed25519)
• ✍️ Package Signing - Cryptographically signs your packages
• 📝 Transparency Logging - Records all signing events in immutable logs
• 🔍 Security Scanning - Audits your package before publishing
• 🌐 Provenance Tracking - Tracks package origins and build metadata

🚀 Quick Start

Installation

npm install -g gasha

System Check

gasha doctor

This checks if you have all required dependencies:

• ✅ Node.js 16+
• ✅ Python 3.7+
• ✅ Docker (for sandboxing) - with helpful installation links
• ✅ OpenSSL (for key generation) - with helpful installation links
• ✅ Python cryptography library

Note: Missing dependencies show helpful installation links for easy setup.

For Package Consumers

Install a package securely:

gasha install express

What happens:

• Downloads package from npm registry
• Computes SHA256 hash
• Verifies cryptographic signature (if available)
• Runs security audit (detects risky patterns)
• Extracts package in sandboxed Docker container
• Installs to your node_modules

Audit any package for security issues:

gasha audit lodash --ai

Output:

• Security findings with risk scores
• Suspicious code patterns detected
• Optional AI-powered risk summary

For Package Publishers

Generate cryptographic keys:

gasha keygen --out ./keys --algo ed25519

Sign your package:

gasha sign ./dist/my-package.tgz --key ./keys/private.pem

Verify signatures:

gasha verify ./dist/my-package.tgz --key ./keys/public.pem

Note: Supports both RSA and Ed25519 key verification with automatic detection.

View transparency log:

gasha log view

🛡️ Security Features Explained

SHA256 Integrity Verification

• Computes cryptographic hash of every package
• Prevents tampering during download/transit
• Compares against known good hashes

Cryptographic Signing

• RSA 2048-bit and Ed25519 key support
• Packages signed with private keys
• Verification with public keys
• Prevents unauthorized package modifications

Sandboxed Installation

• Uses Docker containers with strict security policies:
  • --read-only filesystem
  • --network=none (no network access)
  • --cap-drop=ALL (no special privileges)
  • Non-root user execution
• Prevents malicious postinstall scripts

Static Security Auditing

Detects suspicious patterns:

• eval() usage (code injection risk)
• child_process calls (arbitrary execution)
• execSync usage (synchronous execution)
• postinstall scripts (lifecycle hooks)
• process.env access (environment variables)

Transparency Logging

• Merkle tree structure for immutable logs
• Records all signing events
• Cryptographic integrity verification
• Tamper-evident audit trail

AI-Powered Analysis

• Optional OpenAI integration
• Intelligent risk assessment
• Natural language security summaries
• Context-aware threat detection

🧰 Complete CLI Reference

Command	Description	Example
gasha install <pkg>	Install package securely	gasha install express
gasha verify <pkg>	Verify package signature	gasha verify ./pkg.tgz
gasha audit <pkg>	Security audit package	gasha audit lodash --ai
gasha sign <path>	Sign a package	gasha sign ./dist --key ./keys/private.pem
gasha keygen	Generate keypair	gasha keygen --out ./keys --algo ed25519
gasha log view	View transparency log	gasha log view
gasha doctor	Check system readiness	gasha doctor
gasha explain <pkg>	Analyze package info & security tips	gasha explain express

Command Options

Key Generation:

gasha keygen --out ./keys --algo ed25519|rsa

Signing:

gasha sign ./package.tgz --key ./private.pem --log ./gasha-log.json --policy strict

Verification:

gasha verify ./package.tgz --key ./public.pem --verbose

Auditing:

gasha audit express --ai --output json

📦 Node.js API

const { verify, sign, audit, keygen } = require('gasha');

// Generate keypair
await keygen('./keys', 'ed25519');

// Sign a package
const success = await sign('./dist/package.tgz', './keys/private.pem');

// Verify a package
const isValid = await verify('./package.tgz', './keys/public.pem');

// Audit a package
const report = await audit('express', { ai: true });
console.log(`Risk score: ${report.score}/100`);
console.log(`Findings: ${report.findings.length}`);

🔧 Use Cases & Examples

For Open Source Maintainers

Secure Package Publishing:

# 1. Generate signing keys
gasha keygen --out ./keys --algo ed25519

# 2. Build your package
npm run build

# 3. Sign the tarball
gasha sign ./dist/my-package-1.0.0.tgz --key ./keys/private.pem

# 4. Publish to npm (with signature)
npm publish ./dist/my-package-1.0.0.tgz

For Enterprise Teams

Secure Dependency Management:

# Audit all dependencies
gasha audit express --ai
gasha audit lodash --ai
gasha audit react --ai

# Install only verified packages
gasha install express
gasha install lodash

For Security Teams

Supply Chain Monitoring:

# Check package integrity
gasha verify ./suspicious-package.tgz --key ./trusted-keys/public.pem

# Audit for malicious patterns
gasha audit ./package --ai --output json > security-report.json

# View signing history
gasha log view

🔑 GitHub Actions Integration

Secure CI/CD Pipeline:

name: Secure Package Publishing
on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install Gasha
        run: npm install -g gasha
        
      - name: Generate Keys
        run: gasha keygen --out ./keys --algo ed25519
        
      - name: Build Package
        run: npm run build
        
      - name: Sign Package
        run: gasha sign ./dist/package.tgz --key ./keys/private.pem
        
      - name: Publish to npm
        run: npm publish ./dist/package.tgz
        env:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

🧭 Roadmap

• ✅ Phase 1 → SHA256 verification, sandboxing, static auditing
• ✅ Phase 2 → Cryptographic signing, transparency logs, AI analysis
• 🚧 Phase 3 → Plugin system, provenance metadata, advanced integrations
• 🚀 Phase 4 → Transparency dashboard, community features

🤝 Contributing

We welcome contributions! Here's how to get started:

• Fork the repository
• Clone your fork: git clone https://github.com/kilopal/gasha.git
• Install dependencies: npm install
• Install Python dependencies: pip install cryptography
• Make your changes in the lib/ directory
• Test your changes: npm test
• Submit a pull request

Development Setup

# Clone and setup
git clone https://github.com/kilopal/gasha.git
cd gasha
npm install
pip install cryptography

# Run tests
npm test

# Test CLI
node bin/gasha.js test-run

📜 License

MIT © 2025 Mockilo Labs

🆘 Support & Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: Security Policy

Gasha - Making the npm ecosystem safer, one package at a time. 🛡️