ghsafe

🛡️ ghsafe — GitHub Repository Security Analyzer

Don't run that repo! Scan GitHub repositories for phishing, malware, and suspicious code before you clone and run them.

🎯 Why ghsafe?

A developer friend received a job opportunity on LinkedIn from someone pretending to be from a well-known tech company. They asked him to check out a GitHub repository — a seemingly normal coding exercise. Luckily, my friend reviewed the code first and found hidden data exfiltration, environment variable theft, and obfuscated payloads buried inside.

Not everyone is that careful. ghsafe is a CLI tool that scans any GitHub repository for malicious patterns before you run it, helping protect developers from:

• 🎣 Phishing repos disguised as job opportunities or coding tests
• 💀 Malware hidden in postinstall scripts
• 🔑 Credential theft targeting SSH keys, API tokens, and browser data
• ⛏️ Crypto miners embedded in seemingly normal projects
• 🕳️ Backdoors and persistence mechanisms

📦 Installation

# Run directly with npx (no install needed)
npx ghsafe scan https://github.com/user/suspicious-repo

# Or install globally
npm install -g ghsafe

🚀 Usage

Scan a GitHub Repository

npx ghsafe scan https://github.com/user/suspicious-repo

Scan a Local Directory

npx ghsafe scan ./path/to/project

Enable AI-Powered Analysis

# Recommended: Use GitHub Models (via your GitHub token)
export GITHUB_TOKEN=your-github-token
npx ghsafe scan https://github.com/user/repo --ai

# Alternative: Use OpenAI directly
export OPENAI_API_KEY=your-openai-key
npx ghsafe scan https://github.com/user/repo --ai

JSON Output (for CI/CD)

npx ghsafe scan ./project --json

🔍 What It Detects

Category	Examples	Severity
Network Exfiltration	Webhook URLs, raw IP connections, tunneling services	🟠 HIGH
Data Exfiltration	SSH key theft, env var collection, browser data access, crypto wallets	🔴 CRITICAL
Code Obfuscation	eval(), Function(), Base64/hex payloads, String.fromCharCode	🟠 HIGH
Dangerous Execution	child_process, shell commands, download-and-exec pipelines	🔴 CRITICAL
Crypto Mining	Mining pool connections, known miner libraries, wallet addresses	🔴 CRITICAL
Persistence	Crontab manipulation, shell profile modification, startup scripts	🟠 HIGH
Suspicious Install Scripts	postinstall hooks that run code, download scripts	🔴 CRITICAL

📊 Output

ghsafe produces a rich terminal report with:

• Risk Score (0-100) with visual bar
• Verdict: ✅ SAFE / ⚠️ SUSPICIOUS / 🚨 DANGEROUS
• Category Summary with severity-coded findings
• Findings Table with file, line number, and description
• Code Previews showing suspicious lines in context
• AI Analysis (optional) with threat assessment and recommendations

Example Output

╭────────── 🛡️  ghsafe — Scan Report ──────────╮
│                                              │
│   Target:     https://github.com/user/repo   │
│   Scanned:    42 files                       │
│   Findings:   13                             │
│   Risk Score: ████████████████████ 100/100   │
│   Verdict:    🚨 DANGEROUS                   │
│                                              │
╰──────────────────────────────────────────────╯

  Category Summary

  🟠 Network Exfiltration: 2 findings
  🔴 Data Exfiltration: 3 findings
  🟠 Code Obfuscation: 2 findings
  🔴 Dangerous Execution: 3 findings
  🔴 Crypto Mining: 1 finding
  🟠 Persistence: 1 finding
  🔴 Suspicious Install Scripts: 1 finding

🤖 AI-Powered Analysis

When you enable the --ai flag, ghsafe sends a summary of the findings to an AI model for deeper contextual analysis.

GitHub Models (Recommended)

ghsafe integrates natively with GitHub Models — using your existing GITHUB_TOKEN to access AI models through GitHub's infrastructure. No additional API keys needed if you already have a GitHub token.

export GITHUB_TOKEN=your-github-token
npx ghsafe scan https://github.com/user/repo --ai

OpenAI (Fallback)

If GITHUB_TOKEN is not set, ghsafe falls back to OpenAI directly.

export OPENAI_API_KEY=your-openai-key
npx ghsafe scan https://github.com/user/repo --ai

AI analysis helps:

• Distinguish false positives from real threats
• Understand the intent behind suspicious patterns
• Get actionable recommendations

Note: AI analysis is optional. The basic static scan works without any API keys or tokens.

🏗️ Architecture

src/
├── index.ts              # CLI entry point (Commander.js)
├── scanner/
│   ├── static.ts          # Static pattern scanner engine
│   ├── ai.ts              # AI-powered analysis (OpenAI)
│   └── rules/
│       ├── network.ts     # Network exfiltration rules
│       ├── obfuscation.ts # Code obfuscation rules
│       ├── exfiltration.ts# Data theft rules
│       ├── execution.ts   # Dangerous execution rules
│       ├── crypto.ts      # Crypto mining rules
│       ├── persistence.ts # Persistence mechanism rules
│       ├── install-scripts.ts # Suspicious install scripts
│       └── index.ts       # Rule registry
├── repo/
│   ├── loader.ts          # GitHub URL cloning / local path loading
│   └── file-walker.ts     # Directory traversal with filtering
├── report/
│   ├── renderer.ts        # Rich terminal output
│   └── types.ts           # TypeScript type definitions
└── utils/
    └── config.ts          # Configuration constants

🔧 Exit Codes

Code	Meaning
0	Repository is safe
1	Suspicious patterns found
2	Dangerous patterns detected

This makes ghsafe easy to integrate into CI/CD pipelines.

🛠️ Built With

• TypeScript — Type-safe development
• Commander.js — CLI framework
• chalk, ora, boxen, cli-table3 — Rich terminal UI
• simple-git — Git operations
• OpenAI SDK — AI-powered analysis
• tsup — Fast TypeScript bundler
• GitHub Copilot CLI — AI-assisted development throughout

📄 License

MIT — see LICENSE

Built with ❤️ and 🛡️ to protect developers from malicious repositories.