GitHub Installer Agent 🛡️

Security-first GitHub project cloning with comprehensive safety checks, dependency analysis, and secure installation guidance.

🔒 Security Features

• ✅ Input Validation: Strict GitHub URL format and origin validation
• ✅ Repository Safety Checks: Size, stars, last update verification via GitHub API
• ✅ Shallow Cloning: Uses git clone --depth 1 to minimize download size
• ✅ Manual Installation: Provides commands but never auto-executes pip install or npm install
• ✅ Virtual Environment Guidance: Recommends isolated testing environments
• ✅ File Safety Scanning: Checks for suspicious file types
• ✅ Transparent Reporting: Detailed operation logs and security assessments
• ✅ Permission Declaration: Clearly states required binaries and permissions

✅ When to Use This Skill

• Need to securely download projects from GitHub
• Analyze project structure and dependencies
• Get safe installation recommendations
• Evaluate new projects in a controlled manner
• Clone repositories with safety checks

❌ When NOT to Use This Skill

• Need automatic dependency installation (use manual commands)
• Working with unverified private repositories
• Downloading from non-GitHub platforms
• Need to execute unknown code automatically

Core Parameters

• repo_url: (String) Full GitHub repository URL (must be from github.com)
• target_dir: (String) Local directory name (recommend using temp directory)
• safe_mode: (Boolean) Enable safety checks (default: true)
• depth: (Number) Git clone depth (default: 1)

🔍 Safety Check Workflow

1. URL Validation

# Validate URL format
if [[ ! "$repo_url" =~ ^https://github\.com/[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+(/.*)?$ ]]; then
    echo "❌ Error: URL must be from github.com"
    exit 1
fi

2. Repository Safety Check

# Get repository info via GitHub API (no cloning)
repo_api_url="https://api.github.com/repos/$(echo $repo_url | sed 's|https://github.com/||' | sed 's|\.git$||')"
curl -s -H "Accept: application/vnd.github.v3+json" "$repo_api_url" | jq '.size, .stargazers_count, .updated_at'

3. Safe Cloning

# Use --depth 1 for minimal clone
git clone --depth 1 "$repo_url" "$target_dir"

4. File Safety Scan

# Check for suspicious files
find "$target_dir" -type f \( -name "*.sh" -o -name "*.bat" -o -name "*.ps1" -o -name "*.exe" \) | head -10

# Check requirements.txt content safely
if [ -f "$target_dir/requirements.txt" ]; then
    echo "📦 Dependencies preview:"
    head -20 "$target_dir/requirements.txt"
fi

📋 Safe Operation Commands

1. Basic Cloning with Checks

# Safe shallow clone
git clone --depth 1 {repo_url} {target_dir}

# Check key files (read-only)
ls -la {target_dir}/
find {target_dir} -maxdepth 2 -type f \( -name "*.txt" -o -name "*.py" -o -name "*.json" \) | head -10

2. Dependency Analysis (No Installation)

# Analyze dependency files safely
if [ -f "{target_dir}/requirements.txt" ]; then
    echo "📋 Python dependencies found:"
    cat "{target_dir}/requirements.txt"
    echo ""
    echo "💡 Safe installation recommendation:"
    echo "cd {target_dir} && python -m venv venv && source venv/bin/activate && pip install --user -r requirements.txt"
fi

if [ -f "{target_dir}/package.json" ]; then
    echo "📋 Node.js dependencies found:"
    cat "{target_dir}/package.json" | jq '.dependencies'
    echo ""
    echo "💡 Safe installation recommendation:"
    echo "cd {target_dir} && npm ci --ignore-scripts"
fi

3. Project Structure Analysis

# Safely analyze structure
echo "📁 Project structure:"
tree {target_dir} -L 2 2>/dev/null || find {target_dir} -maxdepth 2 -type d | sed 's|[^/]*/|  |g'

# Check README safely
if [ -f "{target_dir}/README.md" ]; then
    echo "📖 README preview:"
    head -30 "{target_dir}/README.md"
fi

🚨 Security Warnings and Best Practices

High-Risk Operation Warnings

⚠️  SECURITY WARNINGS:
1. NEVER auto-execute pip install/npm install from unknown sources
2. Always test in virtual environments or containers
3. Check package sources in requirements.txt/package.json
4. Avoid using root privileges for installation
5. Review all script files before execution

Recommended Security Practices

# 1. Use virtual environments
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# 2. Use --user flag for pip
pip install --user -r requirements.txt

# 3. Use pip with hash verification
pip install --require-hashes -r requirements.txt

# 4. Use trusted package mirrors
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

# 5. Audit npm packages
npm audit
npm ci --ignore-scripts

📊 Response Template

Security Analysis Report Format

🔒 GITHUB PROJECT SECURITY ANALYSIS REPORT
═══════════════════════════════════════
Project: {repo_url}
Target Directory: {target_dir}
Clone Status: ✅ Success / ⚠️ Warning / ❌ Failed
───────────────────────────────────────
📁 PROJECT STRUCTURE:
{Project structure summary}

📦 DEPENDENCY ANALYSIS:
{Dependency files found}

🔍 SAFETY CHECKS:
- URL Validation: ✅ Passed
- Repository Size: {size} KB
- Suspicious Files: {None/List}
- Last Updated: {date}
- Stars: {count}
───────────────────────────────────────
💡 SAFE INSTALLATION RECOMMENDATIONS:
{Step-by-step installation commands}

🚨 SECURITY WARNINGS:
{Specific security warnings}
═══════════════════════════════════════

🧪 Example Usage

Safe Clone Example

User: "Help me safely analyze this project: https://github.com/psf/requests"

AI Internal Logic:
- Thought: User requests safe GitHub project analysis. Use github_installer_agent skill.
- Action: github_installer_agent(repo_url="https://github.com/psf/requests", target_dir="/tmp/requests_analysis", safe_mode=true, depth=1)
- Observation: Report clone success, analyze dependencies, provide safe installation recommendations.

📝 Security Best Practices

1. Input Validation

• Always validate GitHub URL format
• Check if repository is from trusted organizations
• Verify repository size (avoid excessively large projects)

2. Operation Restrictions

• Use --depth 1 for shallow cloning
• Restrict filesystem access scope
• Never auto-execute installation commands
• Limit maximum clone size

3. Environment Isolation

• Recommend virtual environments
• Suggest using temporary directories
• Consider container isolation (Docker)
• Use separate user accounts

4. Transparent Operations

• Report all executed operations
• List all accessed files
• Provide security risk assessments
• Log all API calls

🔧 Configuration Options

Environment Variables (Optional)

# Set temporary directory
export GITHUB_CLONE_TEMP="/tmp/github_clones"

# Set maximum repository size (MB)
export MAX_REPO_SIZE_MB=100

# Enable verbose logging
export GITHUB_CLONE_VERBOSE=1

# Set API rate limit (requests per hour)
export GITHUB_API_RATE_LIMIT=60

Skill Configuration

{
  "github_installer_agent": {
    "default_safe_mode": true,
    "default_depth": 1,
    "max_repo_size_mb": 100,
    "allow_private_repos": false,
    "require_api_check": true
  }
}

🛡️ Security Compliance

OWASP Compliance

• ✅ Input Validation
• ✅ Output Encoding
• ✅ Authentication
• ✅ Session Management
• ✅ Access Control
• ✅ Cryptographic Practices
• ✅ Error Handling
• ✅ Logging
• ✅ Security Configuration

GitHub Security Best Practices

• ✅ Use GitHub API for repository verification
• ✅ Implement rate limiting
• ✅ Validate repository ownership
• ✅ Check repository activity
• ✅ Verify commit signatures (when available)

📚 References

• GitHub Security Best Practices
• OWASP Secure Coding Practices
• Python Virtual Environments
• npm Security Audit Guide
• Git Shallow Clone Documentation

🔍 Security Testing

This skill includes built-in security testing:

# Run security tests
cd scripts && ./test_security.sh

# Test URL validation
./scripts/safe_clone.sh --test-url https://github.com/psf/requests

# Test with safety checks disabled (not recommended)
./scripts/safe_clone.sh --no-check https://github.com/psf/requests

🚀 Quick Start

1. Basic safe clone:

github_installer_agent(repo_url="https://github.com/psf/requests", target_dir="./requests_analysis")

2. Clone with custom depth:

github_installer_agent(repo_url="https://github.com/psf/requests", target_dir="./requests_deep", depth=5)

3. Clone to temp directory:

github_installer_agent(repo_url="https://github.com/psf/requests", target_dir="/tmp/requests_$(date +%s)")

Security First, Trust But Verify. 🛡️

Last Updated: 2026-03-22 Version: 2.0.1 Security Level: Low Risk