Typosentinel

TypoSentinel

A comprehensive typosquatting detection tool that helps identify malicious packages across multiple package managers and programming languages.

🚀 Features

• Multi-Language Support: Detects typosquatting across npm, PyPI, Go modules, Maven, NuGet, and more
• Advanced Detection: Uses machine learning and heuristic analysis for accurate threat detection
• Real-time Scanning: Continuous monitoring of package dependencies
• REST API: Easy integration with existing CI/CD pipelines
• Plugin Architecture: Extensible system for custom analyzers
• Performance Optimized: Efficient scanning with caching and parallel processing
• Comprehensive Reporting: Detailed analysis reports with risk scoring

📦 Installation

Binary Releases

Download the latest release from GitHub Releases:

# Linux
wget https://github.com/Alivanroy/Typosentinel/releases/latest/download/typosentinel-linux-amd64
chmod +x typosentinel-linux-amd64
sudo mv typosentinel-linux-amd64 /usr/local/bin/typosentinel

# macOS
wget https://github.com/Alivanroy/Typosentinel/releases/latest/download/typosentinel-darwin-amd64
chmod +x typosentinel-darwin-amd64
sudo mv typosentinel-darwin-amd64 /usr/local/bin/typosentinel

# Windows
# Download typosentinel-windows-amd64.exe and add to PATH

From Source

git clone https://github.com/Alivanroy/Typosentinel.git
cd Typosentinel
make build
# Binary will be created as ./typosentinel

Docker

docker pull typosentinel:latest
docker run --rm -v $(pwd):/workspace typosentinel:latest scan /workspace

🔧 Quick Start

Basic Usage

# Scan a project directory
typosentinel scan /path/to/project

# Scan specific package managers
typosentinel scan --package-manager npm /path/to/project
typosentinel scan --package-manager pypi /path/to/project

# Output results to file
typosentinel scan --output report.json /path/to/project

# Enable verbose logging
typosentinel scan --verbose /path/to/project

Real-World Examples

🚀 CI/CD Pipeline Integration

GitHub Actions Example:

# .github/workflows/security-scan.yml
name: Security Scan
on: [push, pull_request]

jobs:
  typo-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Download TypoSentinel
        run: |
          wget https://github.com/Alivanroy/Typosentinel/releases/latest/download/typosentinel-linux-amd64
          chmod +x typosentinel-linux-amd64
          sudo mv typosentinel-linux-amd64 /usr/local/bin/typosentinel
      - name: Scan for typosquatting
        run: |
          typosentinel scan --output sarif --output-file results.sarif .
          # Fail build only on high-confidence detections
          typosentinel scan --fail-on malicious --format json .
      - name: Upload results to GitHub Security
        uses: github/codeql-action/upload-sarif@v2
        if: always()
        with:
          sarif_file: results.sarif

GitLab CI Example:

# .gitlab-ci.yml
typo_scan:
  stage: security
  image: alpine:latest
  before_script:
    - apk add --no-cache wget
    - wget -O typosentinel https://github.com/Alivanroy/Typosentinel/releases/latest/download/typosentinel-linux-amd64
    - chmod +x typosentinel
  script:
    - ./typosentinel scan --output gitlab-sast --output-file gl-sast-report.json .
  artifacts:
    reports:
      sast: gl-sast-report.json
    expire_in: 1 week
  only:
    - merge_requests
    - main

🏢 Enterprise Development Workflow

Pre-commit Hook Setup:

# Install pre-commit hook
echo '#!/bin/bash
typosentinel scan --fast --fail-on suspicious .' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

# Or use with pre-commit framework
# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: typosentinel
        name: TypoSentinel Security Scan
        entry: typosentinel scan --fail-on malicious
        language: system
        pass_filenames: false
        always_run: true

Corporate Environment with Proxy:

# Configure for corporate proxy
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

# Scan with custom registry mirrors
typosentinel scan \
  --npm-registry https://npm.company.com \
  --pypi-index https://pypi.company.com/simple \
  --timeout 60s \
  /path/to/project

🔍 Security Audit Scenarios

Comprehensive Security Audit:

# Full audit with all detection methods
typosentinel scan \
  --enable-all-detectors \
  --similarity-threshold 0.6 \
  --include-dev-dependencies \
  --output detailed-report.json \
  --format json \
  /path/to/project

# Generate executive summary
typosentinel report \
  --input detailed-report.json \
  --template executive \
  --output audit-summary.pdf

Supply Chain Risk Assessment:

# Analyze dependency tree for risks
typosentinel analyze \
  --depth 5 \
  --check-maintainers \
  --verify-signatures \
  --output supply-chain-report.json \
  /path/to/project

# Check for abandoned packages
typosentinel scan \
  --check-maintenance \
  --min-download-threshold 1000 \
  --max-age 365d \
  /path/to/project

🐍 Python Project Examples

Django Application:

# Scan Django project with virtual environment
source venv/bin/activate
typosentinel scan \
  --package-manager pypi \
  --requirements requirements.txt \
  --requirements requirements-dev.txt \
  --exclude-patterns "*/migrations/*" \
  .

# Check for malicious packages in production requirements
typosentinel scan \
  --package-manager pypi \
  --requirements requirements.txt \
  --fail-on suspicious \
  --output production-scan.json \
  .

Data Science Project:

# Scan Jupyter notebook dependencies
typosentinel scan \
  --package-manager pypi \
  --include-notebooks \
  --check-imports \
  --ml-enhanced \
  /path/to/notebooks

# Scan conda environment
typosentinel scan \
  --package-manager conda \
  --environment-file environment.yml \
  --check-channels \
  .

📦 Node.js Project Examples

React Application:

# Scan React app with comprehensive checks
typosentinel scan \
  --package-manager npm \
  --include-dev-deps \
  --check-scripts \
  --verify-integrity \
  --output react-security-report.json \
  .

# Pre-deployment security check
typosentinel scan \
  --package-manager npm \
  --production-only \
  --fail-on malicious \
  --format sarif \
  .

Monorepo Scanning:

# Scan multiple packages in monorepo
typosentinel scan \
  --recursive \
  --package-manager npm \
  --workspace-aware \
  --consolidate-report \
  --output monorepo-scan.json \
  .

# Scan specific workspace
typosentinel scan \
  --package-manager npm \
  --workspace packages/frontend \
  .

🔧 Go Project Examples

Microservice Application:

# Scan Go microservice
typosentinel scan \
  --package-manager go \
  --check-go-sum \
  --verify-checksums \
  --include-indirect \
  /path/to/microservice

# Check for malicious modules in go.mod
typosentinel scan \
  --package-manager go \
  --go-mod-file go.mod \
  --fail-on suspicious \
  .

🐳 Docker Integration

Container Security Scanning:

# Scan dependencies in Docker build
docker run --rm \
  -v $(pwd):/workspace \
  -v ~/.typosentinel:/root/.typosentinel \
  typosentinel:latest scan \
  --output /workspace/container-scan.json \
  /workspace

# Multi-stage build with security scanning
# Dockerfile
FROM typosentinel:latest as security-scanner
COPY package.json requirements.txt ./
RUN typosentinel scan --fail-on malicious .

FROM node:18-alpine as production
COPY --from=security-scanner /app .
# ... rest of build

🔄 Continuous Monitoring

Scheduled Security Scans:

# Daily security scan (crontab)
0 2 * * * /usr/local/bin/typosentinel scan \
  --config /etc/typosentinel/config.yaml \
  --output /var/log/typosentinel/daily-$(date +\%Y\%m\%d).json \
  /path/to/projects

# Weekly comprehensive audit
0 1 * * 0 /usr/local/bin/typosentinel audit \
  --comprehensive \
  --email-report security@company.com \
  /path/to/projects

Integration with Security Tools:

# Send results to SIEM
typosentinel scan \
  --output json \
  --webhook https://siem.company.com/api/security-events \
  /path/to/project

# Integration with Slack notifications
typosentinel scan \
  --output json \
  --on-suspicious "slack-notify #security-alerts" \
  --on-malicious "slack-notify #critical-security" \
  /path/to/project

Configuration

Create a configuration file config.yaml:

api:
  host: "0.0.0.0"
  port: 8080
  timeout: 30s

scanning:
  package_managers:
    - npm
    - pypi
    - go
  parallel_workers: 4
  cache_enabled: true
  cache_ttl: 24h

ml:
  enabled: true
  model_path: "./models"
  threshold: 0.7

logging:
  level: "info"
  format: "json"
  output: "stdout"

REST API

Start the API server:

typosentinel serve --config config.yaml

API endpoints:

# Health check
curl http://localhost:8080/health

# Scan packages
curl -X POST http://localhost:8080/api/v1/scan \
  -H "Content-Type: application/json" \
  -d '{"packages": ["express", "lodash"], "package_manager": "npm"}'

# Get scan results
curl http://localhost:8080/api/v1/results/{scan_id}

📖 Documentation

• User Guide - Comprehensive usage guide
• API Documentation - REST API reference
• Troubleshooting Guide - Common issues and solutions
• Plugin Development - Creating custom analyzers
• Configuration Reference - All configuration options

🛠️ Development

Prerequisites

• Go 1.23 or later
• Make (optional)
• Docker (for containerized development)

Setup Development Environment

git clone https://github.com/Alivanroy/Typosentinel.git
cd Typosentinel
make dev-setup

Available Make Targets

make help                # Show all available targets
make build              # Build the binary
make test               # Run tests
make test-coverage      # Run tests with coverage
make lint               # Run linters
make fmt                # Format code
make clean              # Clean build artifacts
make docker-build       # Build Docker image

Running Tests

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run benchmarks
make benchmark

# Run performance tests
make perf-test

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   CLI Client    │    │   REST API      │    │   Web UI        │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                        ┌─────────────────┐
                        │  Core Engine    │
                        └─────────────────┘
                                 │
            ┌────────────────────┼────────────────────┐
            │                    │                    │
       ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
       │  Scanner    │    │  Detector   │    │ ML Engine   │
       │  Module     │    │  Module     │    │  Module     │
       └─────────────┘    └─────────────┘    └─────────────┘
            │                    │                    │
       ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
       │ Package     │    │ Reputation  │    │ Feature     │
       │ Managers    │    │ Analysis    │    │ Extraction  │
       └─────────────┘    └─────────────┘    └─────────────┘

🔍 Detection Methods

1. String Similarity Analysis

• Levenshtein distance
• Jaro-Winkler similarity
• Longest common subsequence

2. Visual Similarity Detection

• Unicode homoglyph detection
• Character substitution patterns
• Font rendering analysis

3. Machine Learning

• Package metadata analysis
• Behavioral pattern recognition
• Risk scoring algorithms

4. Reputation Analysis

• Author verification
• Download statistics
• Community feedback

📊 Performance

Performance Metrics

• Scanning Speed: 1000+ packages per minute
• Memory Usage: < 100MB for typical workloads
• Detection Accuracy: High precision with low false positive rates
• Response Time: < 60ms for safe packages, < 2s for threat analysis
• Supported Formats: 15+ package managers

Detection Capabilities

TypoSentinel effectively detects various types of typosquatting attacks including:

• Character substitution (e.g., expresss vs express)
• Character omission (e.g., lodahs vs lodash)
• Character insertion (e.g., recat vs react)
• Homoglyph attacks using similar-looking characters
• Domain squatting and namespace confusion

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: make test
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔒 Security

For security vulnerabilities, please see our Security Policy.

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Project Documentation

🙏 Acknowledgments

• Thanks to all contributors who have helped improve this project
• Inspired by the need for better supply chain security
• Built with ❤️ for the open source community

📈 Roadmap

• Support for more package managers (Cargo, Composer, etc.)
• Enhanced machine learning models
• Real-time threat intelligence integration
• Advanced visualization dashboard
• Enterprise features and support

Made with ❤️ by Alivanroy