API ve otomasyon

TraceMint'in HTTP API'si web arayüzünün kullandığı işlemleri otomasyona açar. REST yollarının çoğu /api/v1 altında bulunur. Endpoint'e erişmek için oturum veya uygun kapsamlı API anahtarı gerekir; rol, kuruluş ve proje üyeliği ayrıca uygulanır. Yönetim arayüzünden anahtar oluşturma ve iptal etme adımları Settings bölümündedir.

Kimlik doğrulama ve en düşük yetki

Bir otomasyon için kuruluşunuzun uygulama taban adresini kullanın. API anahtarını X-API-Key başlığında gönderin; başına sk_ eklemeyin. Oluşturulan ham anahtar yalnız bir kez gösterilir. Uygun scope örnekleri projects.read, scans.read, scans.write, findings.read, export.read, settings.manage ve etkin pentest için pentest:read / pentest:write / pentest:report değerleridir. Bir anahtar sahibinin rolünden daha geniş yetki alamaz; proje sınırı varsa diğer projelere erişemez.

Örnek, anahtarı komut satırında açıkça yazmadan okunabilir proje listesini ister:

read -r -s TM_API_KEY
curl --fail-with-body --silent --show-error \
  -H "X-API-Key: ${TM_API_KEY}" \
  'https://staging.tracemint.ai:8080/api/v1/projects?page=1&page_size=20'
unset TM_API_KEY

Bu örnekte page 1'den başlar, page_size 1–100 aralığındadır. Girişten dönen bearer token da Authorization: Bearer <token> ile kullanılabilir; etkileşimli oturumun süre/iptal davranışına bağlıdır. Gizli değeri URL sorgusuna, kaynak depoya veya paylaşılan loga koymayın.

Sık kullanılan işlem yolları

İşlem	Yöntem ve yol	Temel izin
Projeleri listele	GET /api/v1/projects	projects.read
Proje oluştur	POST /api/v1/projects	projects.write
Tarama modlarını öğren	GET /api/v1/scans/modes	Geçerli oturum veya API anahtarı
Proje taraması başlat	POST /api/v1/scans/projects/{project_id}/scans	scans.write ve proje erişimi
Tarama durumunu oku	GET /api/v1/scans/{scan_id}	scans.read ve proje erişimi
Taramaları karşılaştır	GET /api/v1/scans/{base_scan_id}/compare/{compare_scan_id}	scans.read, iki taramaya erişim ve karşılaştırılabilirlik koşulları
Bulguları filtrele	GET /api/v1/findings	findings.read
GitOps kanıtıyla değerlendirme	POST /api/v1/gitops/argocd/evaluate	findings.read ve erişilebilir tarama
GitOps scan kanıt kuyruğu	GET /api/v1/gitops/argocd/applications	findings.read ve erişilebilir tarama verisi
Kyverno/Gatekeeper YAML üret	POST /api/v1/gitops/admission-policy/export	findings.read

Yazma isteklerinin JSON alanlarını ezbere varsaymayın: ilgili ekranın formunu veya kuruluşunuzun sürümüne ait API sözleşmesini kullanın. Örneğin GitOps değerlendirmesinde uygulama, namespace, cluster, scan ID, commit SHA ve değişmez image digest birlikte bağlanır. deployment_gate.status=allowed tek başına tüm kanıtların tamamlandığı anlamına gelmez; quality_gate.passed, kontrol sonuçları ve evidence_chain alanlarını birlikte değerlendirin. Admission YAML üretme işlemi cluster'a uygulama yapmaz.

GET /api/v1/gitops/argocd/applications en yeni 5.000 tarama kaydı penceresindeki tamamlanmış taramalardan satırlar türetir; tüm tarihçeyi veya canlı ArgoCD uygulama envanterini vermez. limit 1–100, offset 0–10000, gate all/blocked/allowed; isteğe bağlı environment ve q filtreleri vardır. Yanıttaki pagination.has_more ile sonraki sayfaya geçin. Bir uygulamanın tekrarlanan taramaları ayrı satır olabilir.

Yanıt ve hata davranışı

• 401: anahtar/oturum geçersiz, süresi dolmuş veya iptal edilmiş; gizli değeri yenileyin.
• 403: izin ya da proje erişimi yetersiz; rol ve anahtar scope'unu yöneticinizle doğrulayın.
• 404: kaynak bulunmuyor veya erişilebilir değil; doğru kuruluş/proje/tarama kimliğini kontrol edin.
• 409: kayıt/sürüm çakışması; güncel sunucu durumunu yeniden okuyup isteği tekrar değerlendirin.
• 422: istek gövdesi veya alan kısıtı geçersiz; detail içindeki alan hatalarını düzeltin.
• 429: hız sınırı; istek sıklığını azaltıp yeniden deneyin.

API hata yanıtları genelde JSON detail alanını içerir. Başarısız liste isteğini “hiç bulgu yok” sonucuna dönüştürmeyin. Sayfalama ve filtrelerin sunucu tarafında olduğu ekranlarda yalnız ilk sayfayı toplam sonuç gibi kullanmayın.

Şema ve gerçek zamanlı durum

/docs, /redoc ve /openapi.json varsayılan olarak kapalıdır; kuruluş operatörü TRACEMINT_ENABLE_PUBLIC_DOCS ile açarsa kendi sürümünüzün şemasını oradan okuyabilirsiniz. Tarama ilerlemesi için uygulama WebSocket kullanır; yalnız HTTP isteğinin dönmesine bakarak taramanın tamamlandığını varsaymayın. İşin durumunu GET /api/v1/scans/{scan_id} üzerinden de sorgulayabilirsiniz.

API kullanımında sıralama: anahtarı sınırlı scope ile oluşturun → erişimi bir GET ile doğrulayın → yazma isteğinden önce hedef/kapsamı teyit edin → dönen ID'yi kaydedin → durum ve kanıtı ayrı sorgulayın → artık kullanılmayan anahtarı iptal edin.