Github Installer Agent

一键从 GitHub 克隆项目，识别依赖文件并自动安装 Python 库，提供项目结构和运行方式初步分析建议。

Security Scan

The skill generally matches its stated purpose (securely cloning and analyzing GitHub repos) but contains several internal inconsistencies and a few behaviors you should review before use.

Purpose & Capability

The skill's code and SKILL.md line up with the declared purpose: safe URL validation, shallow git clone, dependency file inspection, and advisory-only installation guidance. However, registry-level metadata lists no required binaries while the SKILL.md frontmatter and README explicitly require git, curl, jq, ls, cat. Also the package is described as 'instruction-only / no install spec' but includes multiple scripts (safe_clone.sh, test_security.sh, validate_skill.sh). These mismatches (registry metadata vs SKILL.md/_meta.json vs included scripts) are incoherent and worth a manual check.

Instruction Scope

Runtime instructions stay within cloning/analysis scope (calling GitHub API, reading files, listing trees, printing dependency files). The scripts do read and print repo files (requirements.txt, README, etc.) which can expose repository source or embedded secrets to the agent/user — this is expected for analysis but you should be aware. The Response Template explicitly references including 'Full source of all included files', which means the skill will surface full file contents; verify you are comfortable with that. Scripts also perform filesystem operations (rm -rf on target_dir when overwriting) and may change permissions, and include interactive prompts; these are functional but require user caution.

Install Mechanism

There is no network install step or external download; the skill is delivered as scripts and documentation (no install spec), which reduces supply-chain risk. All executable logic is in bundled bash scripts. No suspicious external installers or obscure download URLs were found.

Credentials

The skill does not require credentials or special environment variables to run. The README documents optional env vars (GITHUB_CLONE_TEMP, MAX_REPO_SIZE_MB, GITHUB_CLONE_VERBOSE) and suggests using a GitHub token for higher API rate limits, but no secrets are declared as required. This is proportionate. Still, because the skill reads and prints file contents from arbitrary repos, cloned repos might contain secrets — run in an isolated environment and audit outputs before sharing them.

Persistence & Privilege

The skill does not request permanent 'always:true' inclusion and does not attempt to modify other skills or global agent configuration. It does modify local filesystem state when cloning and will prompt to delete an existing target_dir if overwriting. That filesystem modification is expected for a cloning utility but should be used carefully (it can rm -rf a target directory).

Scan Findings in Context

[pre-scan-none] expected: Static pre-scan reported no injection signals. The presence of bash scripts with filesystem operations and curl/git usage is expected for this skill's purpose.

What to consider before installing

This skill appears to do what it claims (safe GitHub cloning and analysis), but there are mismatches you should verify before installing or running it: - Metadata inconsistency: registry metadata reported 'no required binaries' while SKILL.md and README require git, curl, jq, ls, cat. Confirm the runtime environment provides those tools or install them from trusted package sources. - Validate included scripts: the repository bundles scripts (scripts/safe_clone.sh, test_security.sh, validate_skill.sh). Inspect these files yourself before running. Pay attention to the rm -rf behavior when overwriting target directories and the fact scripts may chmod files to be executable. - Expect output of file contents: the skill intentionally reads and prints README, requirements.txt, package.json, and may surface 'full source of included files' per its response template. If you plan to analyze private or sensitive repositories, avoid exposing outputs to untrusted destinations and run the skill in an isolated sandbox/container. - Rate limits and tokens: unauthenticated GitHub API calls are used; consider providing a personal access token only if you understand the implications and store it securely (the skill does not request or require a token by default). - Validation scripts contain checks that reference metadata fields not present in the supplied _meta.json; this suggests maintenance or packaging oversights — treat the skill as not fully vetted and run scripts like test_security.sh in a controlled environment first. Recommended actions before use: manually review the three scripts, run test_security.sh locally in an isolated environment, avoid running automatic install commands (pip/npm) on untrusted code, and prefer using temporary containers or VMs for repository analysis.

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