Denetim, adım adım.The audit, step by step.

07

kalkan nasıl çalışırHow kalkan works

kalkan iki parçadan oluşur. Motor deterministik bir Python aracıdır ve bir karar vermek için hiçbir dil modelini çağırmaz. Ajanlar, Claude Code içinde çalışan alt ajanlardır. Her ajan kaynağı okur ve tek bir sonuç dosyası yazar (kabuk yok, web yok, düzenleme yok). kalkan audit ve kalkan unattended, ajan işi için Claude Code (veya Codex) turları başlatır.

kalkan has two parts. The engine is a deterministic Python tool, and it makes no model call to decide a verdict. The agents are subagents in Claude Code. Each agent reads the source and writes one result file (no shell, no web, no edits). kalkan audit and kalkan unattended start Claude Code (or Codex) rounds for the agent work.

Motor bütün durumu diskte tutar ve her sonraki adımı seçer. Her ajan sonucunu şemaya ve alıntılara karşı kontrol eder. Kararları kendisi hesaplar. Bu yüzden bir denetim, kullanım limitinden sonra kaldığı yerden devam eder.

The engine keeps all state on disk and chooses every next step. It checks every agent result against its schema and its quotes. It computes the verdicts itself. Thus an audit continues where it stopped after a usage limit.

AşamalarPhases

1. 01Hazırlık. Motor hedefi kopyalar. Hedefin ajan talimat dosyalarını (CLAUDE.md, AGENTS.md ve diğerleri) etkisiz kılar.Prep. The engine copies the target. It neutralizes the agent instruction files of the target (CLAUDE.md, AGENTS.md and others).
2. 02Tarayıcılar. 22 sabit sürümlü araç (Go dahil) kopyayı sırayla ve ağsız tarar.Scanners. 22 pinned tools (Go included) scan the copy one after another, without network.
3. 03SCA. Motor bağımlılıkları yerel zafiyet veritabanlarıyla eşleştirir.SCA. The engine matches the dependencies with local vulnerability databases.
4. 04Keşif (ajan). Dört ajan ürünü, rolleri, saldırı yüzeylerini ve çalışma ortamını haritalar.Recon (agents). Four agents map the product, the principals, the attack surfaces and the execution.
5. 05Plan. Motor kapsam defterini yazar. Her yüzey ve zafiyet sınıfı bir birimdir.Plan. The engine writes the coverage ledger. Each surface and vulnerability class is one unit.
6. 06Av ve eleştirmen (ajan). Avcılar birimleri arar. Eleştirmen boşlukları bulur. Profile göre 1 ile 3 dalga çalışır.Hunt and critic (agents). Hunters search the units. A critic finds the gaps. 1 to 3 waves run, by profile.
7. 07Doğrulama (ajan). Doğrulayıcılar şüphelileri çürütmeye çalışır. Son inceleme ve birleştirme de bu aşamada çalışır.Validate (agents). Verifiers try to refute the candidates. The final review and the consolidation also run in this phase.
8. 08PoC. Docker varsa sandbox kod bulgularını kilitli bir konteynerde dener.PoC. With Docker, the sandbox tries the code findings in a locked container.
9. 09Birleştirme ve rapor. Motor bütün sonuçları birleştirir ve raporu yazar.Merge and report. The engine merges all results and writes the report.

--tools-only 4. ile 8. adımları atlar. Ayrıntılar ve örnek bir doğrulama: Nasıl çalışır.

--tools-only skips steps 4 to 8. Details and a sample verification: How it works.

08

Araçlar ve tarayıcılarTools and scanners

kalkan 22 aracı sabit sürümle kurar: 21 tarayıcı ve Go araç zinciri. Kurulum, indirilen 15 programı ve Go araç zincirini sabit bir SHA-256 değeriyle kontrol eder. pip, 4 Python aracını (checkov, bandit, flawfinder, gixy) tam sürümüyle kurar, hash kontrolü yapmaz. Go checksum veritabanı, go install ile derlenen 2 aracı (govulncheck, poutine) kontrol eder. Senin Go kurman gerekmez.

kalkan installs 22 tools at pinned versions: 21 scanners and the Go toolchain. Setup checks the 15 downloaded programs and the Go toolchain against a pinned SHA-256. pip installs the 4 Python tools (checkov, bandit, flawfinder, gixy) by exact version, without a hash check. The Go checksum database checks the 2 tools that go install builds (govulncheck, poutine). You do not need to install Go.

Sürümler ve görevler: Araçlar. Tarayıcılar varsayılan olarak hedefin kendi bastırma işaretlerini (# nosec, gitleaks:allow, checkov:skip ve diğerleri) yok sayar. kalkan scan --honor-suppressions bu işaretleri dikkate alır.

Versions and roles: Tools. By default, the scanners ignore the suppression markers of the target (# nosec, gitleaks:allow, checkov:skip and others). kalkan scan --honor-suppressions keeps them.

Kurulum yeriInstall location

Araçlar veri klasörünün .tools/ klasöründe durur: bkz. Nereye kurar?

The tools are in the .tools/ folder of the data folder: see Where does it install it?

• <tool>/<version>/bin/17 araç. 15 araç hazır program olarak gelir. kalkan govulncheck ve poutine araçlarını Go ile kaynaktan derler.17 tools. 15 tools come as ready-made programs. kalkan builds govulncheck and poutine from source with Go.
• pyenv/4 pip aracı ayrı bir venv'de: Checkov, Bandit, flawfinder, gixy.4 pip tools in their own venv: Checkov, Bandit, flawfinder, gixy.
• go/Go 1.26.9 araç zinciri. gosec ve govulncheck onunla çalışır.The Go 1.26.9 toolchain. gosec and govulncheck run with it.
• installed.jsonkalkan'ın kurduğu her aracın sürümü, yolu ve SHA-256 değeri.The version, the path and the SHA-256 of each tool that kalkan installed.
• cache/opengrep/opengrep çalışma ortamı. kalkan onu ilk kullanımda açar (289,8 MB, bir Windows 11 makinesinde bir kez ölçüldü).The opengrep runtime. kalkan unpacks it on first use (289.8 MB, measured once on one Windows 11 machine).

Araçları kontrol etCheck the tools

kalkan doctor
kalkan tools list
kalkan tools verify --quick

kalkan doctor her aracı, veritabanlarını, git'i ve Claude Code oturumunu kontrol eder. Sorunlu her satır kendi düzeltme komutunu yazar, örneğin kalkan tools install --force gosec. kalkan tools verify kurulu her dosyanın SHA-256 değerini yeniden hesaplar. Go'nun 15.045 dosyası için bu iş 8 dakika sürdü (virüs tarayıcılı bir Windows 11 makinesinde bir kez ölçüldü). --quick hızlı kontroldür.

kalkan doctor checks every tool, the databases, git and the Claude Code login. Each failed row names its own fix, for example kalkan tools install --force gosec. kalkan tools verify hashes every installed file again. For the 15,045 files of Go, this took 8 minutes (measured once on one Windows 11 machine with a virus scanner). --quick is the fast check.

Windows on ARM (windows-arm64) için Trivy, Opengrep, Hadolint ve Grype derlemesi yok. kalkan bu tarayıcıları atlar ve nedenini yazar.Trivy, Opengrep, Hadolint and Grype have no build for Windows on ARM (windows-arm64). kalkan skips these scanners and records the reason.

09

Ajan doğrulamasıAI verification

Tarayıcılar çok sayıda şüpheli üretir. Bir araç sonucu, bir ajan onu kaynak kodda doğrulayana kadar doğrulanmamış araç sonucu olarak kalır. Rapor bu sonuçları ayrı bir listede gösterir.

The scanners produce many candidates. A tool result stays an unverified tool result until an agent verifies it in the source code. The report shows these results in a separate list.

AjanlarThe agents

kalkan'ın 10 ajan rolü var. Her ajan kaynağı okur ve tek bir sonuç dosyası yazar: kendi sonucunu. Kabuk yok, web yok, düzenleme yok.

kalkan has 10 agent roles. Each agent reads the source and writes one result file: its own result. No shell, no web, no edits.

• reconÜrünü, rolleri, saldırı yüzeylerini ve çalışma ortamını alıntılarla haritalar.Maps the product, the principals, the attack surfaces and the execution, with quotes.
• hunterKapsam birimlerini toplu olarak arar. Kaynağa dayanan iddialar yazar.Searches batches of coverage units. Writes candidates that rest on the source.
• criticBir av dalgasının kapsamını değerlendirir ve eksik birimleri önerir.Judges the coverage of a hunt wave and proposes the missing units.
• verifierBir iddiayı çürütmeye çalışır. Üç kanıt sorusunu alıntılarla yanıtlar.Tries to refute one claim. Answers three evidence questions with quotes.
• reviewerSon kaydı taze gözle okur. Kararı verified, downgrade veya reject olur.Reads a final record with fresh eyes. Its decision is verified, downgrade or reject.
• consolidatorAynı kök nedeni ve aynı düzeltmeyi paylaşan kayıtları gruplar.Groups the records that share one root cause and one fix.
• sca-reachKodun bir bağımlılığın zafiyetli kısmına ulaşıp ulaşmadığına alıntılarla karar verir.Decides with quotes whether the code reaches the vulnerable part of a dependency.
• poc-builderBir bulgu için küçük, güvenli bir doğrulama programı yazar. Motor onu sandbox içinde çalıştırır.Writes a small, safe verification program for one finding. The engine runs it in the sandbox.
• polisherTürkçe bulgu metinlerinde eksik Türkçe harfleri geri koyar.Restores missing Turkish letters in the Turkish finding texts.
• translatorBulgu metinlerini İngilizce rapor için çevirir.Translates the finding texts for the English report.

KararlarVerdicts

Doğrulayıcı her şüpheli için üç soruyu yanıtlar. Saldırgan girdiyi kontrol ediyor mu? Bir yetki sınırı aşılıyor mu? Bir önlem eksik mi? Her yanıt kaynak koddan bir alıntı taşır. Motor her alıntıyı dosyada arar (±2 satır). Dosyada olmayan bir alıntı kanıt sayılmaz.

The verifier answers three questions about each candidate. Does an attacker control the input? Does it cross a privilege boundary? Is a mitigation missing? Each answer quotes the source code. The engine looks up every quote in the file (±2 lines). A quote that is not in the file counts as no evidence.

• confirmedDoğrulanan bulgu: üç yanıtın üçü de kanıtlı.Confirmed finding: all three answers are established.
• needs_validationDoğrulama bekleyen bulgu: kanıt ne onaya ne ret kararına yeter.Finding that needs validation: the evidence is not enough to confirm or to reject.
• rejectedReddedilen şüpheli: doğrulanmış tek bir çürütme yeter.Rejected candidate: one verified refutation is enough.

Hangi araç sonuçları doğrulanır?Which tool results get verified?

Avcılar araç sonuçlarını ipucu olarak görür. Av aşaması bitince motor, kritik ve yüksek ciddiyetli kod sonuçları için doğrulama görevleri açar. Bu görevler bütçenin sınırlı bir payını kullanır. Doğrulama görevi almayan bir sonuç, raporda doğrulanmamış araç sonucu olarak kalır.

The hunters see the tool results as hints. After the hunt, the engine creates verify tasks for code results with critical or high severity. These tasks use a limited share of the budget. A result without a verify task stays in the report as an unverified tool result.

Son incelemeFinal review

standard ve deep profillerinde taze bir gözden geçirici her doğrulanan ve doğrulama bekleyen kaydı yeniden okur. Doğrulayıcının gerekçesini görmez. Motor bir kararı yalnız korur veya zayıflatır, hiçbir zaman güçlendirmez. fast profilinde ayrı bir son inceleme yoktur.

In the standard and deep profiles, a fresh reviewer reads each confirmed record and each record that needs validation again. The reviewer does not see the reasoning of the verifier. The engine keeps or weakens a verdict, and it never makes a verdict stronger. The fast profile has no separate final review.

Yalnızca araç moduTools-only mode

--tools-only hiçbir ajan çalıştırmaz. Motor keşif, plan, av, doğrulama ve PoC aşamalarını atlar. Rapor her sonucu doğrulanmamış araç sonucu olarak gösterir ve genel riski bilinmiyor olarak yazar. Bu mod Claude Code istemez.

--tools-only runs no agent. The engine skips the recon, plan, hunt, validate and PoC phases. The report shows every result as an unverified tool result and gives the overall risk as unknown. This mode needs no Claude Code.

10

PoC sandbox

Statik kanıt bir bulgunun kodda var olduğunu gösterir. Sandbox bir adım daha atar: bulguyu izole bir konteynerde çalıştırıp etkinin gerçekten oluştuğunu gösterir.

Static evidence shows that a finding exists in the code. The sandbox goes one step further: it runs the finding in an isolated container and shows that the effect really happens.

Bir bulgu doğrulandıktan sonra ajan küçük bir doğrulama programı yazar. Motor bu programı kilitli bir konteynerde çalıştırır ve çıktısına bakar. Program beklenen etkiyi gösterirse bulgu confirmed olur ve güven düzeyi high'a çıkar. Göstermezse bulgu kararını korur. Sandbox hiçbir zaman bir bulgunun derecesini düşürmez, yalnızca yükseltir.

After a finding is verified, the agent writes a small verification program. The engine runs it in a locked container and reads its output. If the program shows the expected effect, the finding becomes confirmed and its confidence rises to high. If it does not, the finding keeps its verdict. The sandbox never lowers a finding, it only raises one.

Konteyner neyle kilitlenirHow the container is locked

• Ağ yokNo network--network none. Konteynerin hiçbir ağ arayüzü yoktur. Dışarıya tek bir paket gidemez.--network none. The container has no network interface. Not one packet can leave it.
• Salt-okunur hedefRead-only targetKodun kopyası /target altına salt-okunur bağlanır. Program koda yazamaz.The copy of the code is mounted read-only at /target. The program cannot write to the code.
• Root değilNot rootKullanıcı 65534 (nobody), bütün Linux yetenekleri düşürülür, no-new-privileges açıktır.User 65534 (nobody), every Linux capability is dropped, and no-new-privileges is on.
• Yazılabilir tek yerOne writable placeKök dosya sistemi salt-okunurdur. Yalnızca /out ve /tmp yazılabilir.The root filesystem is read-only. Only /out and /tmp are writable.
• SınırlarLimits1 CPU, 512 MB bellek, 256 işlem, 180 saniye. Süre dolarsa konteyner zorla kapatılır.1 CPU, 512 MB memory, 256 processes, 180 seconds. If the time runs out, the container is forced down.
• Sahte veriDummy dataProgram yalnızca sahte veri kullanır, en küçük gözlemlenebilir etkide durur ve hiçbir gerçek sisteme dokunmaz.The program uses dummy data only, stops at the smallest observable effect and never touches a real system.
• Disk ve bellekDisk and memoryMotor her çıktı akışından en çok 256 KB tutar. /out 64 MB'ı veya 1.000 dosyayı geçerse motor konteyneri durdurur ve klasörü siler.The engine keeps at most 256 KB of each output stream. If /out passes 64 MB or 1,000 files, the engine stops the container and deletes the folder.
• Sır gizlemeRedactionMotor çıktıyı ve kanıt dosyalarını yazmadan önce anahtar, token ve şifre gibi değerleri [REDACTED] yapar.Before it writes the output and the evidence files, the engine replaces values such as keys, tokens and passwords with [REDACTED].

Açmak içinTurning it on

Sandbox için Docker gerekir. --allow-build-network olmadan kalkan denetim sırasında hiçbir imaj çekmez ve derlemez. Temel imajları önceden sen indirirsin. Her dil için ayrı bir imaj vardır. Yalnızca ihtiyacın olanı indirebilirsin.

The sandbox needs Docker. Without --allow-build-network, kalkan pulls and builds no image during an audit. You download the base images beforehand. There is one image per language, and you can pull only the one you need.

# Status: is Docker running, which images exist
kalkan sandbox status

# Only for Python projects
kalkan sandbox pull python:3.12-slim

# All of them (Python, Node, Go, Java, PHP, Ruby, .NET)
kalkan sandbox pull

İmajlar Docker'ın kendi alanında durur, kalkan klasöründe değil. kalkan yazan yerde motorun tam yolunu kullan: bkz. Komutlar ve yollar.

The images live in Docker's own storage, not in the kalkan folder. Where it says kalkan, use the full engine path: see Commands and paths.

Raporda ne görürsünWhat the report shows

• passedEtki gözlendi. Bulgu confirmed, güven high. Konteynerin çıktısı ve yazdığı dosyalar evidence/<bulgu-id>/ altına kopyalanır.The effect was observed. The finding is confirmed with high confidence. The container output and the files it wrote are copied into evidence/<finding-id>/.
• failedProgram beklenen etkiyi göstermedi. Bulgu kararını korur, PoC sonucu rapora yazılır.The program did not show the expected effect. The finding keeps its verdict, and the PoC result goes into the report.
• blockedPoC çalışmadı. Neden rapora yazılır: süre doldu, /out sınırı aşıldı, temel imaj yok, Docker erişilemedi ya da ajan güvenli bir program yazamadı.The PoC did not run. The report names the reason: the time ran out, /out passed its limit, the base image is missing, Docker was not available, or the agent could not write a safe program.

Raporda her bulgu bir çalışma zamanı doğrulaması satırı taşır: tekrarlandı (PoC etkiyi gösterdi), sonuçsuz (PoC çalıştı ama etkiyi göstermedi) veya yapılmadı (nedeniyle birlikte). Böylece statik kanıtı çalıştırılmış kanıttan ayırırsın.

In the report, each finding has a runtime validation line: reproduced (the PoC showed the effect), inconclusive (the PoC ran but did not show the effect) or not performed (with the reason). Thus you can tell static evidence from evidence that ran.

Birim düzeyi yetmezse ajan uygulama düzeyi PoC seçebilir. Motor projenin compose yığınını yalnız iç ağda, internetsiz ve dışarı port açmadan başlatır, istekleri ayrı bir istemci konteynerinden gönderir. Privileged servis, host ağı, Docker soketi veya hedef dışına bağlama isteyen bir yığın hiç başlatılmaz. İmaj derlemek veya indirmek senin onayını ister: --allow-build-network (isteğe bağlı, varsayılan kapalı). Bu bayrakla PoC sandbox'ı, hedefin compose yığınının imajlarını ağ erişimiyle çeker ve derler. Çalışan yığın internete hiç çıkmaz.

When the unit level is not enough, the agent can choose an app-level PoC. The engine starts the compose stack of the project only on an internal network, without internet and without published ports, and sends the requests from a separate client container. A stack that asks for a privileged service, the host network, the Docker socket or a mount outside the target never starts. Building or pulling images needs your consent: --allow-build-network (opt-in, off by default). With it, the PoC sandbox pulls and builds the images of the target's compose stack with network access. The running stack never gets internet.

11

SCA ve zafiyet veritabanlarıSCA and vulnerability databases

SCA (yazılım bileşen analizi), projenin bağımlılıklarını bilinen zafiyetlerle karşılaştırır. kalkan bunu yalnız yerel veritabanlarıyla yapar. Paket adların ve sürümlerin makineden çıkmaz.

SCA (software composition analysis) compares the dependencies of the project with known vulnerabilities. kalkan does this with local databases only. Your package names and versions do not leave the machine.

1. 01Syft bir SBOM (bileşen listesi) çıkarır. Rapor onu CycloneDX ve SPDX biçiminde yazar.Syft builds an SBOM (a list of components). The report writes it in the CycloneDX and SPDX formats.
2. 02OSV-Scanner ve Grype bileşenleri yerel veritabanlarıyla ağsız eşleştirir.OSV-Scanner and Grype match the components with the local databases, without network.
3. 03RetireJS verisi projeye kopyalanmış JavaScript kütüphanelerini bulur. malicious-dependency kuralı bilinen zararlı paket sürümlerini bulur.The RetireJS data finds JavaScript libraries that the project copied into its files. The malicious-dependency rule finds known malicious package versions.
4. 04govulncheck, Go kodunun zafiyetli koda ulaşıp ulaşmadığını kontrol eder. Diğer dillerde sca-reach ajanı kritik ve yüksek kayıtları alıntılarla kontrol eder.govulncheck checks whether the Go code reaches the vulnerable code. For other languages, the sca-reach agent checks the critical and high records with quotes.

VeritabanlarıThe databases

Veritabanları veri klasörünün .tools/vulndb/ klasöründe durur. 29 Ekim 2026'da toplam 3,67 GB tuttular (bir Windows 11 makinesinde bir kez ölçüldü).

The databases are in the .tools/vulndb/ folder of the data folder. On 29 October 2026, they used 3.67 GB in total (measured once on one Windows 11 machine).

• Grype3,36 GB. Grype'ın zafiyet veritabanı.3.36 GB. The vulnerability database of Grype.
• OSV0,30 GB. 13 ekosistem: npm, PyPI, Go, Maven, RubyGems, Packagist, crates.io, NuGet, Pub, Hex, CRAN, SwiftURL, GitHub Actions.0.30 GB. 13 ecosystems: npm, PyPI, Go, Maven, RubyGems, Packagist, crates.io, NuGet, Pub, Hex, CRAN, SwiftURL, GitHub Actions.
• Go7 MB. govulncheck için vuln.go.dev arşivi.7 MB. The vuln.go.dev archive for govulncheck.
• RetireJS0,6 MB. JavaScript kütüphane deposu.0.6 MB. The JavaScript library repository.

Eksik bir veritabanı çevrimiçi bir sorguya dönüşmez. sca match bir veritabanı boşluğu kaydeder ve rapor bu boşluğu gösterir. --online seçeneği isteğe bağlıdır ve paket adlarını çevrimiçi servislere gönderir.

A missing database never becomes an online query. sca match records a database gap, and the report shows the gap. The --online flag is opt-in, and it sends the package names to online services.

Kilit dosyası (lockfile) olmayan bir projede kalkan tam sürümleri kontrol eder. Sürüm aralıklarını raporda tarama boşluğu olarak listeler.

For a project without a lockfile, kalkan checks the exact versions. The report lists the version ranges as a scan gap.

Güncel tutKeep them current

Yerel eşleştirme yalnız son indirmedeki zafiyetleri bilir. kalkan doctor, bir veritabanı eksikse veya 7 günden eskiyse uyarır. Veritabanlarını bu komut indirir. Komut 24 saatten genç ve sağlam bir veritabanını tutar:

Local matching knows only the vulnerabilities of the last download. kalkan doctor warns when a database is missing or older than 7 days. This command downloads the databases. It keeps a sound database that is younger than 24 hours:

kalkan sca update-db

İndirme yalnız ekosistem adlarını ve arşiv isteklerini gönderir. Projenin hiçbir paketini göndermez. Ayrıntılar: Güncelleme.

The download sends only ecosystem names and archive requests. It never sends a package of the project. Details: Updating.

12

RaporlarReports

kalkan her denetim için ~/kalkan-runs/<run-id>/ klasörünü oluşturur. Rapor dosyaları bu klasörün report/ klasöründedir. Önce EXECUTIVE.html dosyasını aç.

kalkan creates the folder ~/kalkan-runs/<run-id>/ for each audit. The report files are in its report/ folder. Open EXECUTIVE.html first.

• EXECUTIVE.htmlTek sayfalık yönetici özeti: genel risk, en önemli 10 bulgu ve öncelikli eylemler. Bulgu bağlantıları REPORT.html dosyasını açar.The executive summary on one page: the overall risk, the top 10 findings and the priority actions. Its finding links open REPORT.html.
• REPORT.html, REPORT.mdTam rapor: bütün bulgular, kanıtları ve düzeltme önerileri, kapsam, tarama boşlukları ve doğrulanmamış araç sonuçları.The full report: all findings with their evidence and remediation, the coverage, the scan gaps and the unverified tool results.
• findings.jsonBirleştirilmiş bulgular, makine okunur biçimde.The merged findings in a machine-readable form.
• findings.sarifSARIF 2.1.0: bulgular ve SCA kayıtları. GitHub code scanning ve IDE'ler bu dosyayı okur. Doğrulanmamış araç sonuçları bu dosyaya yalnız --include-candidates ile girer: bkz. CI/CD.SARIF 2.1.0: the findings and the SCA records. GitHub code scanning and IDEs read this file. The unverified tool results go into this file only with --include-candidates: see CI/CD.
• summary.jsonSayılar, motorlar, kapsam, bütçe, boşluklar, rapor dosyalarının yolları ve run bilgisi: tip, süre ve kalkan-audit ile çalıştıysa maliyet (USD, API eşdeğeri) ve tokenlar.The counts, the engines, the coverage, the budget, the gaps, the paths of the report files and the run facts: type, time and, for a kalkan-audit run, the cost (USD, API-equivalent) and the tokens.
• sbom.cdx.json, sbom.spdx.jsonBileşen listesi (SBOM): CycloneDX 1.6 ve SPDX 2.3. kalkan bu dosyaları yalnız projede bileşen bulursa yazar.The component list (SBOM): CycloneDX 1.6 and SPDX 2.3. kalkan writes these files only when it finds components in the project.
• *.en.md, *.en.htmlTürkçe bir denetimin İngilizce sürümü: REPORT.en.md, REPORT.en.html ve EXECUTIVE.en.html.The English version of a Turkish run: REPORT.en.md, REPORT.en.html and EXECUTIVE.en.html.

DilLanguage

Rapor varsayılan olarak İngilizce. Türkçe rapor için başlatma komutuna --lang tr ekle. Türkçe rapor yerleşik İngilizce teknik terimleri korur. Claude Code oturumunda kalkan, Türkçe bir denetimin sonunda İngilizce sürümü de sorar. kalkan-audit bu soruya hayır cevabı verir. Türkçe bir denetimin İngilizce raporunu sonradan istemek için şu iki komutu çalıştır:

The report is English by default. For a Turkish report, add --lang tr to the start command. A Turkish report keeps the established English technical terms. In a Claude Code session, kalkan offers the English version at the end of a Turkish run. kalkan-audit answers no to this question. To ask for the English report of a Turkish run later, run these two commands:

kalkan run answer english_report yes --run <run-id>
# Claude Code
/kalkan devam <run-id>

Çevirmen ajanlar bulgu metinlerini çevirir. Sonra motor İngilizce dosyaları yazar.

The translator agents translate the finding texts. Then the engine writes the English files.

Denetim klasörüThe run folder

Rapor dışındaki klasörler denetimin iş dosyalarını tutar.

The other folders hold the work files of the audit.

• target/Denetlenen kodun kopyası. Ajan talimat dosyaları .kalkan-neutralized ekini alır.A copy of the audited code. The agent instruction files get the suffix .kalkan-neutralized.
• source/Git geçmişinin özel kopyası: git URL'sinin klonu veya yerel reponun geçmişi. Gitleaks ve Kingfisher geçmişi burada tarar.A private copy of the git history: the clone of a git URL, or the history of a local repository. Gitleaks and Kingfisher scan the history here.
• scans/Tarayıcıların ham çıktıları ve durum dosyaları.The raw output and the status files of the scanners.
• sca/SBOM ve bağımlılık zafiyeti kayıtları.The SBOM and the dependency vulnerability records.
• tasks/Ajan görevleri: her görevin istemi, girdisi ve sonucu.The agent tasks: the prompt, the input and the result of each task.
• state.jsonDenetimin durumu. devam kaldığı yeri buradan okur.The state of the audit. devam reads the resume point from it.
• DiğerleriOtherŞüpheli listesi, kapsam defteri, bulgular, olay günlüğü ve benzeri iş dosyaları.The candidate list, the coverage ledger, the findings, the event log and similar work files.

Bitmiş bir denetimde raporu tutup kod kopyasını, geçmiş kopyasını ve iş klasörlerini silmek için kalkan run clean <run-id> çalıştır. Ayrıntılar: Disk kullanımı.

To keep the report of a finished audit and delete the code copy, the history copy and the work folders, run kalkan run clean <run-id>. Details: Disk usage.

13

CI/CD

Bir CI hattında (sürekli entegrasyon) yalnızca araç modunu kullan. --tools-only Claude Code istemez ve hiçbir ajan çalıştırmaz. Tarayıcılar, SCA ve rapor çalışır. Sonuçlar doğrulanmamış araç sonuçlarıdır.

In a CI pipeline (continuous integration), use the tools-only mode. --tools-only needs no Claude Code and runs no agent. The scanners, SCA and the report run. The results are unverified tool results.

CI makinesinde plugin yerine bir kalkan checkout'u kullan. Aşağıdaki adımlar Linux ve macOS içindir.

On the CI machine, use a kalkan checkout in place of the plugin. The steps below are for Linux and macOS.

1. 01

   kalkan'ı klonla ve kur. Bootstrap betiği motoru, tarayıcıları ve veritabanlarını checkout'un içine kurar.

   Clone and set up kalkan. The bootstrap script installs the engine, the scanners and the databases in the checkout.

   git clone https://github.com/dtechcloud/kalkan.git "$HOME/kalkan"
   sh "$HOME/kalkan/scripts/bootstrap.sh"

2. 02

   Proje klasöründe yalnızca araç modunda denetle.

   In the project folder, run a tools-only audit.

   "$HOME/kalkan/.venv/bin/kalkan" audit . --tools-only

3. 03

   Doğrulanmamış araç sonuçlarını da SARIF dosyasına yaz.

   Write the unverified tool results into the SARIF file too.

   "$HOME/kalkan/.venv/bin/kalkan" report --formats sarif --include-candidates

4. 04$HOME/kalkan/runs/<run-id>/report/findings.sarif dosyasını yükle, örneğin GitHub code scanning'e. runs/LATEST dosyası çalıştırma kimliğini tutar.Upload $HOME/kalkan/runs/<run-id>/report/findings.sarif, for example to GitHub code scanning. The file runs/LATEST holds the run ID.

3. adım olmadan SARIF dosyası yalnız SCA kayıtlarını taşır, çünkü yalnızca araç modunda hiçbir bulgu doğrulanmaz. 3. adımın eklediği sonuçlar SARIF'te kind: candidate özelliğini taşır.

Without step 3, the SARIF file holds only the SCA records, because no finding gets verified in tools-only mode. The results that step 3 adds carry the property kind: candidate in SARIF.

Denetimler klasörü projenin dışında olmalı. Checkout'ta bu klasör <checkout>/runs klasörüdür. KALKAN_RUNS_DIR yerini değiştirir. Windows'ta motor .venv\Scripts\kalkan.exe olur ve kurulum powershell -ExecutionPolicy Bypass -File scripts\bootstrap.ps1 ile yapılır.

The runs folder must be outside the project. In a checkout, this folder is <checkout>/runs. KALKAN_RUNS_DIR moves it. On Windows, the engine is .venv\Scripts\kalkan.exe, and the setup command is powershell -ExecutionPolicy Bypass -File scripts\bootstrap.ps1.

Çıkış kodlarıExit codes

• 0Denetim bitti. Bulgu veya araç sonucu olsa da kod 0'dır.The audit is done. The code is 0 also when there are findings or tool results.
• 1Denetim eksik kaldı (kısmi rapor var), durdu veya başarısız oldu.The audit is incomplete (a partial report exists), stopped or failed.
• 2Kullanım hatası, örneğin bilinmeyen bir seçenek.A usage error, for example an unknown option.
• 5Kurulum gerekli: bir araç veya veritabanı eksik. CI'da --yes ekleme. O zaman iş, indirme yapmak yerine bu kodla durur.Setup needed: a tool or a database is missing. Do not add --yes in CI. Then the job stops with this code in place of a download.

Bir işi sonuçlara göre durdurmak için summary.json dosyasını oku. Örneğin counts.sca_malicious bilinen zararlı paketleri sayar. counts.tool_results_by_engine araç sonuçlarını motora ve ciddiyete göre sayar.

To stop a job on the results, read summary.json. For example, counts.sca_malicious counts the known malicious packages. counts.tool_results_by_engine counts the tool results by engine and severity.

Kurulumu her işte tekrarlamaDo not repeat the setup in every job

Bootstrap araçları ve zafiyet veritabanlarını indirir. Bu indirme dakikalar sürer ve süresi ağa bağlıdır. Bootstrap 7 günden genç bir veritabanını yeniden indirmez. Kurulu bir checkout'u sonraki işlere taşı veya kalıcı bir CI makinesi kullan. Veritabanlarını kalkan sca update-db ile güncel tut. kalkan doctor 7 günden eski bir veritabanı için uyarır.

The bootstrap script downloads the tools and the vulnerability databases. This download takes minutes, and its time depends on the network. The bootstrap script does not download a database again when it is younger than 7 days. Carry an installed checkout to the next jobs, or use a persistent CI machine. Keep the databases current with kalkan sca update-db. kalkan doctor warns about a database older than 7 days.

Repodaki docker/ klasörü CI için bir imaj tarifi tutar. Bu imaj desteklenen bir kurulum yolu değil: bkz. Neden her şey Docker'da değil?The docker/ folder of the repository holds an image recipe for CI. This image is not a supported install path: see Why not everything in Docker?