Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
159 lines (113 loc) · 5.63 KB

CONTRIBUTING.md

File metadata and controls

159 lines (113 loc) · 5.63 KB
Raw

Berkontribusi pada Kernel Module Examples

Terima kasih telah tertarik untuk berkontribusi! Repositori ini adalah sumber daya edukasi terbuka untuk komunitas keamanan siber dan pembelajar kernel-level programming.

Untuk informasi umum tentang repositori, lihat README.md.

For English version, see CONTRIBUTING.EN.md.

Tujuan Repository

Repositori ini menghimpun contoh kode dan kerangka program (skeleton) untuk membangun Kernel Module di berbagai platform (Linux, FreeBSD, Solaris, Windows). Setiap contoh:

  • fokus pada satu konsep (skeleton, memory allocation, hook syscall, char/block driver, dsb).
  • ringkas dan dapat langsung dikompilasi dengan instruksi yang disertakan.
  • disertai komentar yang menjelaskan konsep, bukan hanya kode kosong.

Cara Berkontribusi

1. Fork dan Clone

git clone https://github.com/YOUR_USERNAME/KernelModule-Examples.git
cd KernelModule-Examples

2. Buat Branch Baru

git checkout -b add/example-name
git checkout -b fix/short-description
git checkout -b improve/documentation

3. Struktur Direktori dan Konvensi Penamaan

platform/
├── basics/                    # konsep dasar LKM (tidak melibatkan device)
│   └── N.nama-konsep/           # contoh: 0.skeleton, 1.hello, 2.memory-alloc
│       ├── code.c
│       └── Makefile
├── drivers/
│   ├── char/                   # character device driver
│   │   └── N.nama-konsep/
│   └── block/                  # block device driver
│       └── N.nama-konsep/
├── payload/                    # payload gaya rootkit (jika relevan untuk platform)
│   └── nama-payload/
├── README.md / README.EN.md
├── _introduction.md / .EN.md   # konsep dasar kernel module di platform ini
├── _preparation.md / .EN.md    # setup toolchain & build environment
└── _commands.md / .EN.md       # cheat-sheet perintah operasional

Konvensi penamaan:

  • Direktori contoh diberi prefix nomor urut dan nama singkat: 0.skeleton, 1.hello, 2.memory-alloc. Nomor menandakan urutan belajar yang disarankan (dari paling dasar), bukan urutan penambahan.
  • Gunakan code.c (atau code.cpp untuk Windows) sebagai nama file source utama.
  • Gunakan test.c untuk program user-space pendamping (misal untuk menguji IOCTL).
  • Gunakan strip (-) sebagai pemisah kata dalam nama direktori, huruf kecil semua: memory-alloc, hook-syscall.
  • File dokumentasi pendukung diberi prefix underscore (_introduction.md, dst) agar terpisah secara visual dari direktori contoh saat di-sort.

4. Template Header Comment untuk code.c Baru

Setiap contoh kode harus memiliki header comment dengan format berikut (sesuaikan bagian yang relevan dengan platform):

/*
    Nama Konsep
    Archive of Reversing.ID

    Tested on <Nama OS + Versi Kernel>

    Penjelasan singkat: apa yang didemonstrasikan contoh ini.

Build:
    $ make

Module info:
    $ modinfo code.ko

List module:
    $ lsmod

Load:
    $ insmod code.ko

Unload:
    $ rmmod code
*/

Sesuaikan bagian Build/Load/Unload dengan tooling platform (kldload/kldunload untuk BSD, modload/modunload untuk Solaris, sc create/sc start untuk Windows, dst — lihat contoh yang sudah ada di platform terkait).

Jika ada langkah pengujian tambahan (misal menulis ke device file, mengirim signal, menjalankan program user-space), tambahkan bagian Testing: di antara Load: dan Unload:.

5. Panduan Coding (C/C++)

  • Ikuti gaya penulisan yang sudah ada di direktori platform yang sama (indentasi 4 spasi, kurung buka di baris baru untuk fungsi, spasi sebelum tanda kurung pada pemanggilan fungsi).
  • Penamaan fungsi dan variabel: snake_case.
  • Beri komentar pada bagian yang menjelaskan konsep (mengapa API ini dipakai, apa akibatnya di kernel), bukan komentar yang hanya mengulang nama fungsi.
  • Setiap module wajib memiliki fungsi inisialisasi dan terminasi yang simetris — apapun yang dialokasikan/didaftarkan saat init harus dibersihkan saat exit.
  • Sertakan Makefile (atau project file) yang teruji — kode harus benar-benar bisa dikompilasi dengan instruksi yang diberikan.

6. Menambah Contoh Baru

Setiap contoh baru wajib menyertakan:

  1. code.c/code.cpp dengan header comment sesuai template di atas.
  2. Makefile (atau project file untuk Windows) yang sudah diuji build-nya.
  3. Update tabel daftar contoh di README.md/README.EN.md direktori platform terkait.

7. Testing Sebelum Submit

  • Kompilasi kode tanpa warning pada environment yang disebutkan di header comment.
  • Load dan unload module untuk memastikan tidak ada crash/panic.
  • Verifikasi tidak ada broken link di dokumentasi yang diubah.

8. Pull Request Process

Sebelum submit, pastikan branch up-to-date:

git fetch origin
git rebase origin/master

Template Deskripsi PR

## Deskripsi
Penjelasan singkat tentang perubahan yang dibuat.

## Tipe Perubahan
- [ ] Contoh/platform baru
- [ ] Perbaikan kode existing
- [ ] Dokumentasi
- [ ] Bug fix

## Platform/Konsep yang Diubah
- Platform: (Linux/BSD/Solaris/Windows)
- Konsep: (basics/drivers/payload)

## Checklist
- [ ] Kode dikompilasi tanpa warning
- [ ] Header comment mengikuti template
- [ ] README platform terkait sudah diupdate
- [ ] Tidak ada broken link

Lisensi

Dengan berkontribusi pada repositori ini, kamu setuju bahwa kontribusimu boleh didistribusikan ulang sebagai bagian dari repositori ini. Pastikan kode yang dikontribusikan tidak melanggar hak cipta atau lisensi pihak ketiga.

Pertanyaan atau Bantuan?

  • Buka issue baru dengan label question.
  • Email pengurus [at] reversing.id
  • Telegram @ReversingID