Cara Membaca dan Menindaklanjuti Laporan CodeAuditAgent

Laporan keamanan hanya berguna jika ia berubah menjadi perbaikan yang di-merge. Laporan CodeAuditAgent dirancang di sekitar hal itu: setiap temuan cukup spesifik untuk diverifikasi dengan cepat dan disertai patch yang bisa Anda sesuaikan. Panduan ini menjelaskan setiap bagian dari sebuah laporan, cara melakukan triase ketika Anda tidak punya security engineer khusus, dan cara memastikan perbaikan Anda benar-benar berhasil.

Apa yang diaudit

Sebuah audit berjalan pada repositori GitHub publik atau snippet kode yang Anda tempelkan. Untuk repositori, CodeAuditAgent membaca branch default. Repositori privat belum bisa diaudit lewat URL, dan belum ada komentar di pull request; hasilnya berada di dasbor dan di hasil ekspor.

Seberapa banyak isi repositori yang dibaca bergantung pada paket Anda. Paket Free mencakup 1 repositori, 3 audit per bulan, dan hingga 20 file per audit. Starter, seharga $49 per bulan, mencakup 5 repositori, 50 audit, dan 40 file per audit. Pro, seharga $199 per bulan, mencakup repositori tanpa batas, 500 audit, dan 80 file per audit. File tunggal yang lebih besar dari 60 KB dilewati. Hitungan audit bulanan direset pada awal setiap bulan kalender (UTC). Snippet yang ditempel juga merupakan cara cepat memeriksa satu file yang Anda khawatirkan sebelum mengaudit seluruh repositori.

Ketika ada file yang tidak disertakan karena batasan tersebut, laporannya diberi label sebagai snapshot parsial. Anggap label itu serius. Laporan parsial yang bersih berarti file yang dibaca terlihat bersih, bukan berarti repositorinya bersih. Jika kode yang paling Anda pedulikan justru terlewat, auditlah sebagai snippet yang ditempel atau pada paket yang mencakup lebih banyak file.

Skor risiko

Di bagian atas setiap laporan ada skor risiko dari 0 hingga 100; ekspor Markdown juga menyebutkan tingkat keparahan keseluruhan di sebelahnya. Semakin tinggi berarti semakin berisiko. Skor itu adalah ringkasan dari temuan pada audit tersebut, berguna untuk dua hal: memutuskan seberapa mendesak sebuah repositori perlu dilihat, dan melacak apakah ia membaik dari waktu ke waktu.

Jangan membaca terlalu jauh perbedaan kecil antara repositori yang tidak berhubungan. Sebuah skor selalu relatif terhadap apa yang diaudit, dan snapshot parsial melihat lebih sedikit kode. Membandingkan repositori yang sama sebelum dan sesudah perbaikan adalah tempat angka itu paling bermakna.

Tingkat keparahan dan keyakinan

Setiap temuan punya tingkat keparahan dan tingkat keyakinan. Keduanya menjawab pertanyaan yang berbeda: tingkat keparahan adalah seberapa buruk akibatnya jika temuan itu nyata, dan keyakinan adalah seberapa yakin si peninjau bahwa temuan itu memang nyata.

• Kritis: langsung bisa dieksploitasi dengan dampak serius, seperti injection pada endpoint publik, pelanggaran autentikasi, atau kredensial produksi yang terpapar.
• Tinggi: celah nyata yang membutuhkan sebuah prasyarat, atau berdampak signifikan tetapi terbatas.
• Sedang: kelemahan yang berarti jika dikombinasikan dengan bug lain, atau berdampak moderat.
• Rendah: masalah pengerasan dan celah pertahanan berlapis.
• Info: pengamatan yang layak diketahui tetapi bukan celah keamanan jika berdiri sendiri.

Keyakinan bernilai tinggi, sedang, atau rendah. Temuan berkeyakinan tinggi punya bukti yang jelas di dalam kode yang dibaca. Temuan berkeyakinan rendah biasanya bergantung pada sesuatu yang tidak bisa dilihat audit, seperti middleware di file lain, sebuah kebijakan database, atau nilai konfigurasi yang diset saat deploy. Keyakinan rendah bukan berarti abaikan; artinya seorang manusia perlu memeriksa konteks yang hilang sebelum memperbaikinya.

Anatomi sebuah temuan

Setiap temuan mengikuti struktur yang sama, sehingga Anda bisa memverifikasinya dalam urutan yang konsisten.

• Judul dan CWE: kelas kelemahannya, seperti CWE-639 untuk authorization bypass melalui kunci yang dikendalikan pengguna. CWE memberi tahu Anda jenis perbaikan apa yang bisa diharapkan.
• Lokasi: file dan barisnya, sehingga Anda bisa langsung membuka kodenya.
• Bukti: kode yang relevan, dikutip dari file tersebut. Pastikan kutipannya cocok dengan kode Anda saat ini; jika baris itu sudah berubah, temuannya mungkin sudah basi.
• Skenario eksploit: bagaimana penyerang akan benar-benar memanfaatkan kelemahan itu, langkah demi langkah. Ini adalah cara tercepat menilai apakah ia nyata dalam konteks Anda.
• Patch remediasi: usulan perubahan dengan gaya kode di sekitarnya.

Perlakukan patch itu sebagai titik awal yang kuat, bukan commit yang siap di-merge. Ia ditulis dari kode yang dibaca audit, sehingga ia mungkin tidak tahu tentang fungsi helper Anda, konvensi ORM Anda, atau sebuah pemanggil di bagian lain dari kode. Patch yang khas berukuran kecil dan tepat sasaran:

--- a/app/api/invoices/[id]/route.ts
+++ b/app/api/invoices/[id]/route.ts
@@
-  const invoice = await db.invoice.findUnique({ where: { id } });
+  const invoice = await db.invoice.findFirst({
+    where: { id, userId: session.user.id },
+  });
   if (!invoice) return Response.json({ error: 'not_found' }, { status: 404 });

Observasi positif dan langkah berikutnya

Laporan juga mencantumkan apa yang sudah dikerjakan dengan baik: query terparameterisasi yang dipakai secara konsisten, secret yang dimuat dari lingkungan, konfigurasi cookie yang ketat. Bagian ini layak dibaca. Ia memberi tahu Anda pola mana yang harus dipertahankan dan disalin ke kode baru, dan berguna saat menjelaskan kondisi sebuah kode kepada orang lain.

Bagian langkah berikutnya yang direkomendasikan mengubah temuan menjadi rencana yang terurut. Ia sering mengelompokkan temuan yang berkaitan, misalnya beberapa cek kepemilikan yang hilang yang paling baik diperbaiki dengan satu helper bersama alih-alih lima patch terpisah.

Alur triase untuk tim kecil

Tanpa security engineer, risikonya bukan mengabaikan laporan; risikonya adalah menghabiskan satu hari untuk temuan rendah sementara temuan kritis menunggu. Urutan sederhana berikut bekerja dengan baik:

• Baca setiap temuan kritis dan tinggi lebih dulu. Untuk masing-masing, baca skenario eksploitnya lalu putuskan: nyata, tidak nyata, atau butuh konteks.
• Perbaiki temuan kritis yang nyata pada hari yang sama. Jika perbaikannya butuh waktu, tambahkan mitigasi sementara seperti menonaktifkan endpoint atau memperketat sebuah cek.
• Untuk temuan yang butuh konteks, periksa bagian yang hilang: adakah middleware, kebijakan di tingkat baris, atau konfigurasi yang sudah mencegahnya? Tuliskan jawabannya.
• Jadwalkan temuan tinggi ke sprint berjalan, yang sedang ke backlog, dan kumpulkan temuan rendah serta info ke dalam satu putaran pengerasan.
• Ketika sebuah temuan ternyata tidak nyata, catat alasannya. Catatan itu menyelamatkan orang berikutnya dari menyelidikinya lagi.

Tugaskan setiap temuan kepada satu pemilik. Temuan yang dimiliki seluruh tim cenderung tidak dimiliki siapa pun.

Penjelajah temuan dan ekspor

Begitu Anda punya beberapa audit, penjelajah temuan lebih mudah dipakai daripada laporan satu per satu. Ia mendaftar temuan lintas audit dan menyaringnya berdasarkan tingkat keparahan, CWE, dan repositori. Menyaring berdasarkan CWE sangat berguna: jika kelemahan yang sama muncul di tiga repositori, biasanya itu menunjuk pada sebuah pola bersama atau helper yang belum ada, dan memperbaiki polanya lebih murah daripada memperbaiki setiap kemunculannya.

Temuan bisa diekspor sebagai CSV dari penjelajah, yang berguna untuk diimpor ke issue tracker atau spreadsheet. Laporan individual bisa diekspor sebagai Markdown, yang enak dibaca di deskripsi pull request, wiki internal, atau pesan kepada kontraktor yang mengerjakan perbaikannya.

Audit ulang untuk memastikan perbaikannya

Sebuah perbaikan belum selesai sampai Anda memeriksanya. Setelah merge, jalankan audit baru pada repositori yang sama. Setiap laporan bisa dibandingkan dengan audit sebelumnya, sehingga Anda bisa melihat temuan mana yang hilang, mana yang bertahan, dan apakah ada yang baru muncul. Skor risiko semestinya turun ketika masalah nyata diperbaiki; jika tidak, lihat perbandingannya untuk mencari tahu sebabnya.

Jaga agar perbandingannya adil. Jika audit pertama berupa snapshot parsial dan yang kedua membaca file yang berbeda, selisihnya mencerminkan cakupan sekaligus perbaikan. Audit dipotong dari jatah bulanan Anda, jadi biasanya lebih hemat mengumpulkan beberapa perbaikan sebelum mengaudit ulang daripada menjalankannya lagi setelah setiap commit.

Apa yang tidak dicakup sebuah laporan

Mengetahui batasannya membantu Anda menutup celahnya. Audit membaca kode sumber Anda; audit tidak memindai dependensi untuk mencari versi yang diketahui rentan, jadi tetap jalankan pemindai dependensi seperti yang sudah tertanam di package manager Anda atau di GitHub. Audit tidak melihat konfigurasi saat deploy, infrastruktur di luar repositori, atau file yang dilewati. Dan seperti peninjau mana pun, manusia atau AI, audit bisa saja keliru: bukti dan tingkat keyakinan ada di sana agar Anda bisa memeriksanya dengan cepat alih-alih menerimanya begitu saja.

Dipakai dengan cara ini, sebuah laporan menjadi daftar perubahan yang pendek dan terprioritaskan dengan bukti yang menyertainya. Perbaiki yang kritis, periksa yang masih meragukan, audit ulang, lalu perhatikan skornya bergerak.