CaptchaAI IP Beyaz Listesine Alma ve API Anahtar Güvenliği

API anahtarınızı korumanın özü üç kuralda toplanır: anahtarı kaynak koda gömmeyin, yalnızca sunucu IP'lerinizi beyaz listeye alın ve anahtarı düzenli döndürün. CaptchaAI anahtarı doğrudan bakiyenize ve thread'lerinize eriştiği için, sızan tek bir anahtar dakikalar içinde planınızı tüketebilir. Bu rehber üç kuralı çalışan Python örnekleriyle uygular.

Kısa özet — üç kural şu:

• Anahtarı kaynak koda gömmeyin. Ortam değişkeni veya commit'lenmeyen bir .env dosyasından okuyun.
• Yalnızca kendi sunucu IP'lerinizi beyaz listeye alın. Anahtar sızsa bile başka bir IP'den gelen istek reddedilir.
• Anahtarı düzenli döndürün. Yedek bir anahtarı hazır tutun ki birincil anahtar sorun verince kesinti yaşamayın.

API anahtarı nereden sızar?

Çoğu sızıntı saldırı değil, dikkatsizliktir: anahtar repoya commit'lenir, istemci koduna gömülür veya log'da görünür. Aşağıdaki şema en sık yolları özetler.

Exposed API key:
  ├── Leaked in Git repository
  ├── Hardcoded in client-side code
  ├── Shared in documentation
  └── Visible in logs

Impact:
  ├── Balance drained by unauthorized users
  ├── Usage spikes from abuse
  └── Key disabled by service provider

En sık karşılaşılan üç sızıntı kaynağı şunlardır:

• Sürüm kontrolü. Anahtar bir kez commit'lendiyse, dosyayı silseniz bile Git geçmişinde kalır.
• İstemci tarafı kod. Tarayıcıya giden JavaScript içine gömülen anahtar herkese açıktır.
• Log ve hata izleri. İstek gövdesini olduğu gibi log'layan servisler anahtarı düz metin olarak diske yazar.

Sunucu IP'lerini beyaz listeye alma

IP beyaz listesi, anahtar güvenliğinin en güçlü katmanıdır: anahtar sızsa bile istek yalnızca izin verdiğiniz IP'lerden kabul edilir. Diğer önlemler sızıntıyı zorlaştırırken, beyaz liste sızıntının etki alanını doğrudan daraltır.

CaptchaAI kontrol panelinizdeki IP kısıtlama ayarına girin ve yalnızca üretim sunucularınızın sabit IP'lerini ekleyin. Pratikte şu üç noktaya dikkat edin:

• Sabit IP kullanın. Dinamik IP'li ortamlarda liste sürekli bozulur; üretimi sabit IP'li bir sunucuya veya NAT ağ geçidine yerleştirin.
• Yerel makinenizi eklemeyin. Geliştirme için ayrı bir anahtar kullanın; kişisel IP'nizi üretim anahtarının listesine koymayın.
• Listeyi düzenli gözden geçirin. Kullanımdan kalkan sunucuların IP'lerini kaldırın; her açık IP bir saldırı yüzeyidir.

Beyaz liste tek başına yeterli değildir; anahtarı yine de güvenli saklamanız ve döndürmeniz gerekir. Ancak üç kuralı birlikte uygularsanız sızan bir anahtarın zarar verme penceresi belirgin biçimde daralır.

Anahtarı güvenli saklamanın temeli

Anahtarı asla kaynak koda gömmeyin

Anahtarı .py dosyasına yazmak, onu Git geçmişine kalıcı işlemek demektir. Bunun yerine ortam değişkeninden veya commit'lenmeyen bir .env dosyasından okuyun.

# BAD — key in source code
API_KEY = "abc123def456"  # DO NOT DO THIS

# GOOD — environment variable
import os
API_KEY = os.environ["CAPTCHAAI_API_KEY"]

# GOOD — .env file (not committed to Git)
from dotenv import load_dotenv
load_dotenv()
API_KEY = os.environ["CAPTCHAAI_API_KEY"]

.env dosyası

# .env (add to .gitignore!)
CAPTCHAAI_API_KEY=your_api_key_here

.gitignore

# Always ignore .env files
.env
.env.local
.env.production

Ortam değişkenine dayalı yapılandırma

Anahtarı okuma ve doğrulamayı tek sınıfta toplayın; anahtar eksikse uygulama ilk çağrıdan önce dursun.

import os


class CaptchaConfig:
    """Load CaptchaAI config from environment."""

    def __init__(self):
        self.api_key = os.environ.get("CAPTCHAAI_API_KEY")
        if not self.api_key:
            raise EnvironmentError(
                "CAPTCHAAI_API_KEY not set. "
                "Set it in your environment or .env file."
            )
        self.base_url = os.environ.get(
            "CAPTCHAAI_URL", "https://ocr.captchaai.com"
        )

    def validate(self):
        """Verify the API key works."""
        import requests
        resp = requests.get(f"{self.base_url}/res.php", params={
            "key": self.api_key,
            "action": "getbalance",
            "json": 1,
        }, timeout=10)
        data = resp.json()
        if data.get("status") != 1:
            raise RuntimeError(f"Invalid API key: {data.get('request')}")
        return float(data["request"])


# Usage
config = CaptchaConfig()
balance = config.validate()
print(f"Key valid, balance: ${balance:.2f}")

Anahtar döndürme

Anahtarı belirli aralıklarla yenileyin ve yedek bir anahtar hazır tutun; birincil sorun verince kod ikincile geçsin.

import os
import datetime


class KeyManager:
    """Manage API key rotation."""

    def __init__(self):
        self.primary_key = os.environ.get("CAPTCHAAI_API_KEY")
        self.secondary_key = os.environ.get("CAPTCHAAI_API_KEY_BACKUP")
        self.active_key = self.primary_key

    def get_key(self):
        return self.active_key

    def rotate(self):
        """Switch to secondary key."""
        if self.secondary_key:
            self.active_key = self.secondary_key
            print("Rotated to secondary key")
        else:
            print("No secondary key configured")

    def test_key(self, key):
        """Verify a key is valid."""
        import requests
        resp = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": key, "action": "getbalance", "json": 1,
        }, timeout=10)
        return resp.json().get("status") == 1


# Usage
keys = KeyManager()

# If primary fails, rotate to secondary
if not keys.test_key(keys.get_key()):
    keys.rotate()

Göndermeden önce isteği doğrulayın

Göndermeden önce doğrulamak, yanlış parametreleri erkenden yakalar.

import requests
import logging

logger = logging.getLogger(__name__)


class SecureSolver:
    """Solver with security best practices."""

    def __init__(self, api_key):
        self.api_key = api_key
        self.base = "https://ocr.captchaai.com"

    def solve(self, method, **params):
        # Validate inputs
        self._validate_params(method, params)

        data = {"key": self.api_key, "method": method, "json": 1}
        data.update(params)

        # Log without exposing key
        logger.info(
            "Submitting %s solve for %s",
            method, params.get("pageurl", "unknown"),
        )

        resp = requests.post(
            f"{self.base}/in.php", data=data, timeout=30,
        )
        return resp.json()

    def _validate_params(self, method, params):
        """Prevent common security mistakes."""
        # Ensure pageurl is a valid URL
        pageurl = params.get("pageurl", "")
        if pageurl and not pageurl.startswith(("http://", "https://")):
            raise ValueError(f"Invalid pageurl: {pageurl}")

        # Ensure method is valid
        valid_methods = {
            "userrecaptcha", "turnstile", "geetest",
            "base64", "post", "bls", "cloudflare_challenge",
        }
        if method not in valid_methods:
            raise ValueError(f"Unknown method: {method}")

Anahtarı log'lara sızdırmadan kayıt tutma

Log satırlarında görünen anahtar en sık gözden kaçan sızıntıdır. 32 karakterlik anahtar desenini bir formatlayıcıyla maskeleyin.

import logging
import re

logger = logging.getLogger(__name__)


class SafeFormatter(logging.Formatter):
    """Redact API keys from log messages."""

    KEY_PATTERN = re.compile(r'[a-f0-9]{32}', re.IGNORECASE)

    def format(self, record):
        msg = super().format(record)
        return self.KEY_PATTERN.sub("[REDACTED]", msg)


# Configure safe logging
handler = logging.StreamHandler()
handler.setFormatter(SafeFormatter("%(levelname)s: %(message)s"))
logger.addHandler(handler)
logger.setLevel(logging.INFO)

# Key is automatically redacted in logs
logger.info(f"Using key: abc123def456ghi789jkl012mno345pq")
# Output: INFO: Using key: [REDACTED]

Docker secrets ile anahtar yönetimi

Container'a alınmış dağıtımlarda anahtarı image'a gömmeyin; ortam değişkeniyle geçirin veya Docker secrets kullanın.

# Dockerfile — DO NOT embed keys here
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install requests
CMD ["python", "solver.py"]

# docker-compose.yml
services:
  solver:
    build: .
    environment:

      - CAPTCHAAI_API_KEY=${CAPTCHAAI_API_KEY}
    # Or use Docker secrets:
    secrets:

      - captchaai_key

secrets:
  captchaai_key:
    file: ./secrets/captchaai_key.txt

CI/CD tarafında güvenlik

GitHub Actions

Anahtarı düz metin değil, depo sırrı (repository secret) olarak tanımlayıp iş adımına enjekte edin.

# .github/workflows/test.yml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:

      - uses: actions/checkout@v4
      - name: Run tests
        env:
          CAPTCHAAI_API_KEY: ${{ secrets.CAPTCHAAI_API_KEY }}
        run: python test_solver.py

Gizli bilgiyi CI çıktısında asla log'lamayın veya echo ile yazdırmayın.

Yerel senaryo: müşteriye teslim edilen otomasyon

Türkiye'de birçok geliştirici, Bionluk veya Upwork üzerinden müşterilere otomasyon teslim ediyor. Anahtarı repoya commit'leyip müşteriyle paylaşmak iki riski doğurur: bakiyenizin yetkisiz tüketilmesi ve — kazınan veriler kişisel veri içeriyorsa — KVKK kapsamında sorumluluk. Sağlıklısı, her ortam için ayrı anahtar tutup her birini kendi ortam değişkeninden beslemek. Aylık ücretini USD ödediğiniz thread tabanlı bir plan (örneğin BASIC ($15/ay, 5 thread)) ortam başına ayrı anahtarlarla yönetilirse bir sızıntının etki alanı çok daha dar kalır.

Sorun giderme

Anahtar güvenliğiyle ilgili en sık karşılaşılan belirtiler ve hızlı çözümleri aşağıda.

Güvenlik kontrol listesi

Yayına almadan önce şu maddeleri tek tek işaretleyin; her biri farklı bir sızıntı yolunu kapatır.

Sık sorulan sorular

Sunucu IP'lerimi beyaz listeye nasıl alırım?

IP kısıtlama seçeneği için CaptchaAI kontrol panelinize bakın. Yalnızca üretim sunucularınızın IP'lerini ekleyin; böylece anahtar sızsa bile başka IP'den gelen istekler reddedilir.

Ortam değişkeni mi yoksa .env dosyası mı kullanmalıyım?

İkisi de anahtarı kaynak kodun dışında tutar. Üretimde platformun ortam değişkenleri (veya sır yöneticisi) daha güvenlidir; yerel geliştirmede .gitignore'a eklenmiş bir .env dosyası pratiktir.

Anahtarımın log'lara düşmesini nasıl engellerim?

Log formatlayıcınıza maskeleme ekleyin: 32 karakterlik anahtar desenini yakalayıp [REDACTED] ile değiştirin. Yukarıdaki SafeFormatter örneği bunu yapar.

Geliştirme ve üretim için ayrı anahtar tutmalı mıyım?

Evet. Geliştirme, hazırlık (staging) ve üretim için ayrı anahtarlar kullanın. Böylece bir geliştirme anahtarı sızarsa etki alanı yalnızca o ortamla sınırlı kalır ve üretim bakiyeniz risk altına girmez.

İlgili kılavuzlar

• anahtar depolama ve döndürme rehberine göz atın
• bakiye kontrolü ve otomatik doldurma için ayrıntılar

Bakiyenizi ve thread'lerinizi koruyun — CaptchaAI API anahtarınızı bugün güvence altına alın.