🔍 scanwrap

A CLI tool to detect code hidden by excessive trailing whitespace - protecting against a specific obfuscation technique used to hide malicious code in plain sight.

🎯 Purpose

Malicious actors exploit a GitHub code rendering behavior to hide malware within legitimate-looking source code. They use statement-terminating characters (like semicolons) followed by excessive whitespace to push malicious code off-screen in the default GitHub file viewer.

scanwrap detects this specific obfuscation technique by identifying lines with:

• Statement-terminating characters (;, :, ,, ), }, ])
• Followed by excessive trailing whitespace (configurable threshold)
• Potentially hiding malicious code beyond the visible area

🚀 Quick Start

Installation

# Install globally via npm
npm install -g scanwrap

# Or run directly with npx
npx scanwrap <path>

Basic Usage

# Scan a single file
scanwrap suspicious.py

# Scan a directory recursively
scanwrap ./project

# Scan with custom threshold
scanwrap ./project --threshold 50

# Scan multiple file types
scanwrap ./project --include py,js,rb

# Output as JSON for automation
scanwrap ./project --json

📋 Command Line Options

Option	Description	Default
<path>	File or directory to scan	Required
-t, --threshold <number>	Whitespace character count threshold	100
-i, --include <extensions>	File extensions to scan (comma-separated)	py
-g, --ignore <paths>	Paths to ignore (comma-separated)	node_modules,.git
-j, --json	Output results in JSON format	false
-v, --version	Show version number
-h, --help	Show help information

📊 Output Examples

Console Output (Default)

🔍 Scanwrap Security Analysis Report

📊 Summary:
   Total files found: 42
   Files scanned: 15
   Suspicious lines found: 2

🚨 Suspicious Lines Detected:

1. ./src/utils.py:23
   Trailing whitespace: 156 characters
   Visible: import base64;
   Hidden: ██████████████████████████████████████████████████... (+106 more)

2. ./lib/helper.py:45
   Trailing whitespace: 203 characters
   Visible: def process():
   Hidden: ██████████████████████████████████████████████████... (+153 more)

⚠️  Manual review recommended for flagged lines.
   Excessive trailing whitespace may hide malicious code.

JSON Output

{
  "summary": {
    "totalFiles": 42,
    "scannedFiles": 15,
    "findingsCount": 2,
    "errorsCount": 0
  },
  "findings": [
    {
      "filePath": "./src/utils.py",
      "lineNumber": 23,
      "lineContent": "import base64;                                                                                                    exec(base64.b64decode('bWFsaWNpb3VzX2NvZGU='))",
      "trailingWhitespace": 156
    }
  ],
  "errors": [],
  "timestamp": "2025-07-31T10:30:00.000Z"
}

🔧 Integration Examples

CI/CD Pipeline (GitHub Actions)

name: Scanwrap Security Check
on: [push, pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install scanwrap
        run: npm install -g scanwrap
      - name: Run security scan
        run: scanwrap . --include py,js,ts --json > scan-results.json
      - name: Upload results
        uses: actions/upload-artifact@v3
        with:
          name: scanwrap-results
          path: scan-results.json

Pre-commit Hook

#!/bin/sh
# .git/hooks/pre-commit
npx scanwrap . --threshold 80
if [ $? -eq 1 ]; then
    echo "⚠️ Suspicious lines detected. Commit blocked."
    exit 1
fi

Package.json Script

{
  "scripts": {
    "security:scan": "scanwrap src --include js,ts --threshold 50",
    "security:scan:json": "scanwrap src --json > security-report.json"
  }
}

🛡️ Exit Codes

Code	Meaning
0	Scan completed successfully, no suspicious lines found
1	Scan completed, suspicious lines were detected
2+	Error occurred during scan (invalid path, permissions, etc.)

🔍 Detection Logic

scanwrap identifies potentially malicious lines using these criteria:

1. Statement Terminators: Line ends with ;, :, ,, ), }, or ]
2. Excessive Whitespace: Trailing whitespace exceeds the threshold (default: 100 characters)
3. Meaningful Content: Line contains actual code beyond just the terminator
4. File Type: Only scans specified file extensions (default: Python files)

🎯 Supported File Types

While the tool works with any text file, common target extensions include:

• Python: .py (primary target, enabled by default)
• JavaScript/TypeScript: .js, .ts, .jsx, .tsx
• Ruby: .rb
• PHP: .php
• Java: .java
• C/C++: .c, .cpp, .h
• Go: .go

🚫 Limitations

• Static Analysis Only: Does not execute or interpret code
• Specific Pattern: Detects only the trailing whitespace obfuscation technique
• False Positives: May flag legitimate code with excessive trailing whitespace
• Text Files Only: Cannot analyze binary files or complex formats

🔧 Development

Prerequisites

• Node.js 16+
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/byigitt/scanwrap.git
cd scanwrap

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run in development mode
npm run dev <path>

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines for details.

Reporting Issues

If you discover a security vulnerability, please create an issue on GitHub with appropriate details.

🙏 Acknowledgments

• Inspired by recent research on GitHub code rendering vulnerabilities
• Built with TypeScript, Commander.js, and Chalk
• Thank you to all contributors and security researchers

---

⚠️ Important: This tool is designed to detect a specific obfuscation technique. It should be used as part of a comprehensive security review process, not as a standalone security solution.