custom-detectors.yaml

منصة	أمر
Linux (Script)	`curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh \
Debian/Ubuntu	`wget https://github.com/trufflesecurity/trufflehog/releases/download/v3.63.0/trufflehog_3.63.0_linux_amd64.deb && sudo dpkg -i trufflehog_3.63.0_linux_amd64.deb`
RHEL/CentOS/Fedora	`wget https://github.com/trufflesecurity/trufflehog/releases/download/v3.63.0/trufflehog_3.63.0_linux_amd64.rpm && sudo rpm -i trufflehog_3.63.0_linux_amd64.rpm`
macOS (Homebrew)	`brew install trufflehog`
Windows (Scoop)	`scoop bucket add trufflesecurity https://github.com/trufflesecurity/scoop-bucket.git && scoop install trufflehog`
Windows (Chocolatey)	`choco install trufflehog`
Docker	`docker pull trufflesecurity/trufflehog:latest`
From Source	`git clone https://github.com/trufflesecurity/trufflehog.git && cd trufflehog && go install`
Verify Installation	`trufflehog --version`

أمر	وصف
`trufflehog --version`	عرض إصدار TruffleHog
`trufflehog --help`	عرض معلومات المساعدة والأوامر المتاحة
`trufflehog git file://.`	افحص مستودع Git في الدليل الحالي
`trufflehog git file:///path/to/repo`	مسح مستودع git المحلي في المسار المحدد
`trufflehog git https://github.com/user/repo.git`	مسح مستودع GitHub عن بعد
`trufflehog git file://. --only-verified`	إظهار الأسرار الموثقة فقط (بيانات الاعتماد النشطة)
`trufflehog git file://. --json`	قم بإخراج النتائج بتنسيق JSON
`trufflehog git file://. --json > secrets.json`	احفظ نتائج المسح في ملف JSON
`trufflehog filesystem --directory=/path/to/scan`	مسح دليل نظام الملفات بحثًا عن الأسرار
`trufflehog filesystem --directory=.`	مسح المجلد الحالي بشكل متكرر
`trufflehog github --org=orgname --token=ghp_xxxxx`	مسح جميع المستودعات في منظمة GitHub
`trufflehog github --repo=https://github.com/user/repo --token=ghp_xxxxx`	مسح مستودع GitHub محدد
`trufflehog gitlab --token=glpat-xxxxx --repo=https://gitlab.com/group/project`	مسح مستودع GitLab
`trufflehog s3 --bucket=my-bucket --region=us-east-1`	مسح دلو AWS S3 بحثًا عن الأسرار
`trufflehog docker --image=nginx:latest`	افحص صورة Docker عن الأسرار المضمنة
`trufflehog git file://. --no-verification`	امسح دون محاولة التحقق من الأسرار
`trufflehog git file://. --fail`	اخرج برمز غير صفري إذا تم العثور على أسرار
`trufflehog git --help`	اعرض المساعدة لأمر مسح git

أمر	وصف
`trufflehog git file://. --since-commit=abc1234 --until-commit=def5678`	مسح نطاق التعهدات المحددة
`trufflehog git file://. --since-commit=HEAD~100`	افحص آخر 100 عملية إرسال
`trufflehog git file://. --max-depth=50`	قيّد المسح إلى أحدث 50 عملية إرسال
`trufflehog git file://. --branch=feature/new-api`	قم بمسح الفرع المحدد فقط
`trufflehog git file://. --branch=""`	افحص جميع الفروع في المستودع
`trufflehog git file://. --config=custom-detectors.yaml`	استخدم ملف تكوين كاشف مخصص
`trufflehog git file://. --exclude-detectors="aws,generic-api-key"`	استبعاد كاشفات السرية المحددة
`trufflehog git file://. --include-detectors="github,gitlab,slack"`	قم بتضمين أجهزة كشف محددة فقط
`trufflehog github --org=myorg --token=ghp_xxxxx --include-repos="backend-,frontend-"`	مسح منظمة GitHub باستخدام نمط مطابقة المستودع
`trufflehog github --org=myorg --token=ghp_xxxxx --exclude-repos="*-archived"`	استبعاد المستودعات المؤرشفة من المسح
`trufflehog github --org=myorg --token=ghp_xxxxx --include-issues --include-pull-requests`	افحص مشكلات وطلبات السحب على GitHub
`trufflehog github --endpoint=https://github.company.com/api/v3 --org=myorg --token=xxxxx`	مسح مثيل GitHub Enterprise
`trufflehog gitlab --token=glpat-xxxxx --group=group-name`	مسح المجموعة الكاملة في GitLab
`trufflehog filesystem --directory=/app --include-paths=".env,.config,*.yaml"`	مسح أنماط ملفات محددة فقط
`trufflehog filesystem --directory=/app --exclude-paths="node_modules/,vendor/"`	استبعاد المجلدات من مسح نظام الملفات
`trufflehog git file://. --concurrency=10`	حدد عدد العمال المتزامنين (الافتراضي: 8)
`trufflehog git file://. --no-update`	تخطي التحقق من التحديثات
`trufflehog s3 --bucket=my-bucket --key=AKIAXXXXX --secret=xxxxx`	مسح S3 باستخدام بيانات اعتماد AWS الصريحة
`trufflehog git file://. --allow-verification-overlap`	السماح بالتحقق من نفس السر باستخدام عدة كاشفات
`trufflehog git file://. --filter-entropy=4.5`	تعيين الحد الأدنى لعتبة الإنتروبيا (الافتراضي: 3.0)

# custom-detectors.yaml
detectors:
  - name: CustomAPIKey
    keywords:
      - custom_api_key
      - customapikey
    regex:
      apikey: '[A-Za-z0-9]{32}'
    verify:
      - endpoint: 'https://api.example.com/verify'
        unsafe: false
        headers:
          - 'Authorization: Bearer {apikey}'
        successIndicators:
          - '"status":"valid"'
        failureIndicators:
          - '"status":"invalid"'
          
  - name: InternalToken
    keywords:
      - internal_token
      - company_token
    regex:
      token: 'int_[A-Za-z0-9]{40}'
```## الاستخدام المتقدم
```bash
# GitHub token for scanning private repositories
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx

# GitLab token for scanning
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxx

# AWS credentials for S3 scanning
export AWS_ACCESS_KEY_ID=AKIAXXXXXXXXXXXXX
export AWS_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export AWS_REGION=us-east-1
```## الإعدادات
`.trufflehogignore`### إعداد الكاشف المخصص
```text
# .trufflehogignore
# Exclude test files
**/test/**
**/tests/**
**/*_test.go

# Exclude dependencies
node_modules/
vendor/
.venv/

# Exclude specific false positives
docs/examples/fake-credentials.md
scripts/test-data.json
```قم بإنشاء ملف إعدادات كاشف مخصص لتحديد أنماط السرية الخاصة بك:
```yaml
# .github/workflows/trufflehog.yml
name: TruffleHog Secret Scanning
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
          
      - name: TruffleHog Scan
        uses: trufflesecurity/trufflehog@main
        with:
          path: ./
          base: ${{ github.event.repository.default_branch }}
          head: HEAD
          extra_args: --only-verified --fail
```### المتغيرات البيئية
```yaml
# .gitlab-ci.yml
trufflehog-scan:
  stage: security
  image: trufflesecurity/trufflehog:latest
  script:
    - trufflehog git file://. --only-verified --fail --json > trufflehog-report.json
  artifacts:
    reports:
      sast: trufflehog-report.json
    when: always
  allow_failure: false
```### ملف استبعاد الأنماط
```groovy
// Jenkinsfile
pipeline {
    agent any
    stages {
        stage('Secret Scanning') {
            steps {
                sh '''
                    docker run --rm -v $(pwd):/scan \
                    trufflesecurity/trufflehog:latest \
                    git file:///scan --only-verified --fail
                '''
            }
        }
    }
}
```قم بإنشاء ملف 
```bash
# Create pre-commit hook
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
echo "Running TruffleHog secret scan..."
trufflehog git file://. --since-commit=HEAD --only-verified --fail

if [ $? -ne 0 ]; then
    echo "⚠️  TruffleHog detected secrets! Commit aborted."
    exit 1
fi
echo "✓ No secrets detected"
EOF

# Make executable
chmod +x .git/hooks/pre-commit
```لاستبعاد أنماط محددة:
```bash
# Comprehensive scan of entire history
trufflehog git file://. --json --no-update > full-audit.json

# Review verified secrets only
trufflehog git file://. --only-verified --json | jq '.[] | {detector: .DetectorName, file: .SourceMetadata.Data.Git.file, commit: .SourceMetadata.Data.Git.commit}'

# Generate summary report
trufflehog git file://. --json | jq -r '.[] | "\(.DetectorName): \(.SourceMetadata.Data.Git.file)"' | sort | uniq -c | sort -rn
```### إعدادات التكامل CI/CD
```bash
#!/bin/bash
# scan-org.sh

ORG_NAME="mycompany"
GITHUB_TOKEN="ghp_xxxxxxxxxxxxx"
OUTPUT_DIR="./scan-results"

mkdir -p $OUTPUT_DIR

# Scan entire organization
trufflehog github \
  --org=$ORG_NAME \
  --token=$GITHUB_TOKEN \
  --only-verified \
  --json > $OUTPUT_DIR/org-scan-$(date +%Y%m%d).json

# Generate summary
jq -r '.[] | "\(.SourceMetadata.Data.Github.repository): \(.DetectorName)"' \
  $OUTPUT_DIR/org-scan-$(date +%Y%m%d).json | \
  sort | uniq -c | sort -rn > $OUTPUT_DIR/summary.txt

echo "Scan complete. Results in $OUTPUT_DIR"
```#### إجراءات GitHub
```bash
# Scan production image
trufflehog docker --image=myapp:latest --only-verified --json > docker-scan.json

# Scan multiple images
for image in nginx:latest postgres:14 redis:alpine; do
    echo "Scanning $image..."
    trufflehog docker --image=$image --only-verified
done

# Scan local images
docker images --format "{{.Repository}}:{{.Tag}}" | \
  grep -v "<none>" | \
  xargs -I {} trufflehog docker --image={}
```#### GitLab CI
```bash
# Create monitoring script
cat > /usr/local/bin/trufflehog-monitor.sh << 'EOF'
#!/bin/bash
REPOS_DIR="/opt/repositories"
REPORT_DIR="/var/log/trufflehog"
DATE=$(date +%Y%m%d)

mkdir -p $REPORT_DIR

for repo in $REPOS_DIR/*; do
    if [ -d "$repo/.git" ]; then
        repo_name=$(basename $repo)
        echo "Scanning $repo_name..."
        
        cd $repo
        git pull --quiet
        
        trufflehog git file://. --only-verified --json \
          > $REPORT_DIR/${repo_name}-${DATE}.json
          
        # Alert if secrets found
        if [ $(jq length $REPORT_DIR/${repo_name}-${DATE}.json) -gt 0 ]; then
            echo "⚠️  Secrets found in $repo_name" | \
              mail -s "TruffleHog Alert: $repo_name" security@company.com
        fi
    fi
done
EOF

chmod +x /usr/local/bin/trufflehog-monitor.sh

# Add to crontab (daily at 2 AM)
echo "0 2 * * * /usr/local/bin/trufflehog-monitor.sh" | crontab -
```#### أنبوب Jenkins
`--only-verified`## حالات الاستخدام الشائعة
`trufflehog git file://.`### حالة الاستخدام 1: خطاف Pre-Commit لمنع الأسرار
`.trufflehogignore`منع الأسرار من الالتزام في مستودعك:
`--filter-entropy`بناءً على قاعدة التعليمات البرمجية الخاصة بك للموازنة بين اكتشاف الأسرار وتقليل الإيجابيات الكاذبة (الإعداد الافتراضي 3.0 يعمل في معظم الحالات).

- **أرشفة وتحليل نتائج المسح**: تخزين نتائج المسح مع الطوابع الزمنية للتدقيق الامتثالي، وتحليل الاتجاهات، وإظهار تحسينات وضع الأمن بمرور الوقت.

## استكشاف الأخطاء وإصلاحها

| مشكلة | حل |
|-------|----------|
| **"No git repository found"** | Ensure you're in a git repository directory or use `git init` to initialize. For remote repos, check URL syntax and network connectivity. |
| **High number of false positives** | Use `--only-verified` to show only active secrets, increase `--filter-entropy` threshold (e.g., `--filter-entropy=4.5`), or create custom exclude patterns in `.trufflehogignore`. |
| **Scan is very slow on large repositories** | Use `--max-depth` to limit commit history depth, `--since-commit` to scan recent changes only, or increase `--concurrency` value (e.g., `--concurrency=16`). |
| **"Rate limit exceeded" for GitHub** | Provide authentication token with `--token=ghp_xxxxx`, wait for rate limit reset, or use GitHub Enterprise endpoint if available. |
| **Docker scan fails with permission errors** | Run Docker commands with `sudo`, add user to docker group (`sudo usermod -aG docker $USER`), or use `docker run --rm -v $(pwd):/scan trufflesecurity/trufflehog:latest`. |
| **Secrets not being verified** | Check internet connectivity for verification requests, use `--allow-verification-overlap` if multiple detectors should verify, or disable verification with `--no-verification` for offline scanning. |
| **Out of memory errors on large scans** | Reduce `--concurrency` value, scan in smaller commit ranges using `--since-commit` and `--until-commit`, or increase system memory allocation. |
| **GitLab/GitHub Enterprise connection fails** | Verify custom endpoint URL with `--endpoint` flag, check token permissions (needs read access to repos), and ensure SSL certificates are valid. |
| **JSON output is malformed** | Ensure you're using latest TruffleHog version, redirect stderr separately (`2>/dev/null`), or use `jq` to validate and format output (`trufflehog ... --json \ | jq`). |
| **Pre-commit hook not triggering** | Verify hook is executable (`chmod +x .git/hooks/pre-commit`), check shebang line is correct (`#!/bin/bash`), and ensure TruffleHog is in PATH. |
| **S3 scan authentication fails** | Set AWS credentials via environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`), use `--key` and `--secret` flags, or configure AWS CLI profile. || **أدوات الكشف المخصصة لا تعمل** | التحقق من بناء YAML في ملف التكوين، والتأكد من تهريب أنماط التعبير العادية بشكل صحيح، والتحقق من تفرد أسماء أدوات الكشف، واختبار أنماط التعبير العادية بشكل منفصل. |